The Macintosh 68000 Development System 

User's Guide 



If you have any comments or suggestions regarding either the 
Macintosh 68000 Development System software or this documentation, 
please send comments to 

Macintosh Development Tools 
Apple Computer, Inc. 

Mail Stop 2T 
20525 Mariani Avenue 
Cupertino, CA 95014 

Your input is extremely valuable in helping us to provide you with 
the best development tools possible. 
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About This Chapter 

This chapter introduces you to the Macintosh 68000 Development System. 
You should be familiar with the use of Macintosh: how to point, click, 
and select. If you aren*t, read Macintosh , your owner* s guide. It 
introduces you to the Finder, the application that manages your 
documents, and to the basic methods for using a Macintosh application. 

You should also be familiar with the assembly language of the Motorola 
MC68000, the microprocessor used in the Macintosh. If you aren*t, read 
the M68000 16/32-Bit Microprocessor Programmer * s Reference Manual , 
supplied with this package. For brevity, this manual will hereafter be 
referred to as the 68000 Reference Manual. For the same reason, the 
MC68000 microprocessor will be referred to as the 68000. 

Programming the Macintosh in assembly language is not a simple task. 

It requires detailed and thorough knowledge of the Macintosh. The 
Inside Macintosh manual provides all the technical information 
programmers need to create Macintosh applications. In places this 
manual assumes you are familiar with certain aspects of the Macintosh. 
Please refer to Inside Macintosh when you come across such passages. 

To help you launch your Macintosh programming career, this development 
system contains an application that displays a menu bar and a window, 
and lets you edit within the window. A listing of the program, called 
Window, is in an appendix; the source for the program is on disk. The 
importance of this program cannot be over-stressed. It shows how to 
initialize and use Macintosh ROM routines, how to support desk 
accessories from your application, and how to support multiple windows 
from an application. Sample desk accessories are also on the disk. 

The following Inside Macintosh chapters are particularly helpful: 

- Inside Macintosh : A Road Map . This chapter contains a sample 
program similar to the Window program but easier to understand 
since it is written in Pascal. 

- Programming Macintosh Applications in Assembly Language . This 
chapter explains the use of the Toolbox and Operating System 
routines in the Macintosh. It describes how to pass parameters to 
the routines, how to call the routines, how calls to the routines 
are dispatched, how the routines return results, and which 68000 
registers you can safely use. 

- The Structure of a_ Macintosh Application . This chapter is 
especially important for proper interaction between the 
application and the Finder. 

- The Resource Manager : A Programmer *s Guide . 

- The Segment Loader : A Programmer *s Guide . 
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Overview 


The Macintosh 68000 Development System includes two disks, named MDS1 
and MDS2. These disks contain a host of useful applications and files. 
To acquaint you with the Macintosh 68000 Development System, these 
files are described below. MDS1 is the disk that should be placed in 
the built-in drive when you start up the development system. In 
general it contains the main applications provided with the system. 


=[ — 1 ■ — 

- - = MDS1 


9 items 

362K in disk 

37K available 



Edit 



icmi 

moj. 


Asm 




Link 


Exec 


fl 

RMaker 


K> 





PackSyms MacDB Nubs 


Empty Folder System Folder 


t<> 

a 




- Edit is the Editor. It is the application with which you enter 
Assembler, Linker, Exec, and RMaker source files. 

- Asm is the Assembler. It translates assembly-language source 
files into relocatable modules that can be linked together into 
one application. 

- Link is the Linker. It connects modules produced by the Assembler 
together into one application. 

- Exec is the Executive. It automates and integrates assembling, 
linking, and the adding of resources to your application. 

- RMaker is the Resource Compiler. It uses the instructions in a 
text file to create a resource file. 

- PackSyms is an application that converts a symbol file into a 
packed symbol file. The use of packed symbol files saves memory, 
time, and disk space. 

- MacDB Nubs is a folder. It contains small programs (Nubs) that 
should be run on the same Macintosh as the program being debugged. 

- System Folder and Empty Folder contain their usual files. 
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MDS2 contains debuggers, sample programs, and useful system definition 
files . 



=1 — 1 ■ — 
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6 items 

393K in disk 

7K available 
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- Debuggers is a folder that contains several Debuggers , providing 
various levels of assembly-language debugging tools 

- Sample Programs is a folder that contains a sample program, some 
sample desk accessories, a sample window definition procedure, and 
their associated files. An example given later in this chapter 
uses files from this folder. 

- Trap Files is a folder. The files in this folder assign trap 
numbers to trap names. These trap names and numbers are listed in 
an appendix. The traps are described in Inside Macintosh . 

- Equ Files is a folder. The files in this folder assign values to 
the constants and absolute memory locations used by the system. 
These constants are described in Inside Macintosh , and can help 
you avoid using incorrect values in your applications. 

- .D Files is a folder that contains packed versions of the files in 
the Trap Files and Equ Files folders. These are the files you 
will probably use with your application. 

- Empty Folder is devoid of the usual files. 
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File Naming Conventions 

Many files are used and created by the various applications in the 
Macintosh 68000 Development System. A file naming convention helps you 
and applications identify the creator and contents of otherwise similar 
files. Each kind of file has a unique extension — a period followed 
by a few letters — appended to the main part of its name. Thus, 
different yet related files are logically associated because they have 
the same base name • For example , 

- Curve. Asm is an assembly-language source file. 

- Curve. Err is a list of errors generated by the Assembler when it 
assembles Curve. Asm. 

A list of all the file extensions is given in the Quick Reference 
appendix. 

The development system is able to create three physically different 
types of files: application files, text files, and binary files. These 
three file types are designated by the following icons: 



Application 


■=_ [\ 


L, 



OOOI 

-= 


10110 

■==- 


01011 


Text File Binary File 


When using the Macintosh, you generally don*t need to worry about the 
names of volumes. However, when using the Macintosh 68000 Development 
System you must sometimes specify volume names. For example, Linker 
control files list the files to be linked. Files mentioned by file 
name only are taken from the volume that contains your Linker control 
file. To specify another volume, use the form: 

Volume Name : File Name 

A colon separates the volume* s name from the file*s name. 


(warning) 

The development system uses a space to indicate the end 
of a file name and a period to indicate a file*s 
extension. Avoid using these two characters in volume 


names . 
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The Editor 


The Editor is used for entering text. Documents created by the Editor 
are used as assembly-language source files, Linker control files, 
Executive control files, and Resource Compiler input files. 

The Editor doesn't provide any of the sophisticated text formatting 
functions available with programs such as MacWrite. It does, however, 
save text as documents of a type known as text-only files. These 
documents can be shared with all other programs that use text-only 
files or that let you paste text from the clipboard. For example, 
documents created by the Editor can be "prettied up" using MacWrite. 

Editor document names should be given the following extensions: 

- .Asm to indicate the main source file for an assembly 

- .Files to indicate a file that contains a list of separate 
assemblies to be performed 

- .Link to indicate a Linker control file 

- .Job to indicate an Executive control file 

- .R to indicate a Resource Compiler source file 
The Editor is described in Chapter 2. 
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The Assembler 


The Assembler translates 68000 assembly-language source documents into 
files containing relocatable code and symbol table information. Such 
files are given the extension .Rel. .Rel files must be linked before 
an executable object file is produced. 

If errors occur during assembly, a list of the errors is placed in a 
•Err file. If a listing of the file is requested, it's placed in a 
•Lst file. 

The Assembler has the following special features : 

- Instructions can be grouped together into macros. Macros are 
invoked by name, and they can be given strings as parameters. 
Partial strings may be used within the macro. 

- It modifies some instructions so that your program can call, jump 
to, or branch to code in other relocatable segments. 

- Conditional assembly instructions allow multiple versions of a 
program to be generated from a single source. 


The Assembler is described in Chapter 3. 
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The Linker 


The Linker combines a number of .Rel files, produced by the Assembler, 
into an application file. An applications name has no extension. A 
symbol table, which is primarily used by the Debugger, is placed into a 
.Map file. If you request a Linker listing, it too is placed into the 
•Map file. 

The files to be linked together are specified in a Linker control file, 
created by the Editor, that has the .Link extension. This file also 
controls segmentation and listing of the program. 

Errors encountered during linking are automatically written to a .LErr 
file . 

The Linker is described in Chapter 4. 
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The Executive 

The Executive automates assembly, linking, and resource compilation. 
Control files, known as .Job files, determine the sequence of 
applications to be executed by the Executive. 

Each command in an Executive control file specifies not only what 
application is to be executed, but also what applications should be 
used upon successful and unsuccessful completion of that application. 

The Executive is described in Chapter 5. 
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A Simple Sample Session 

Here’s a typical session with the Editor, Assembler, and Linker. The 
named files actually exist in the Sample Program folder; you can try 
the example if you wish. 

1. Select the Editor; then, from the File menu, open the file 
Window. Asm on MDS2. This is the source file for the assembly. 

2. To see how errors are handled, enter the line "Syntax Error"; then 
save the updated file by choosing Save from the File menu. 

3. Assemble the file by choosing ASM MDS2 : WINDOW. ASM from the 
Transfer menu. Window. Asm is assembled automatically. 

4. An error occurs in the assembly, so the Assembler places a list of 
errors in the file Window. Err. When the assembly is complete, the 
Editor is launched with the Window. Asm and Window. Err documents 
open. 

5. Select the faulty line and cut it from the document, then transfer 
back to the Assembler. This time Window. Asm assembles 
successfully, and the resulting relocatable code and symbol table 
is placed in Window. Rel. (The file Window. Err is automatically 
removed from the disk.) 

6. Because the assembly was successful, the Executive is launched. 
Transfer to Link. Select and open the file Window. Link, the 
Linker control file. The application produced by linking 
Window. Rel is called Window. The symbol table file is called 
Window. Map . 

The following diagram shows the files involved in this process (the 
error documents are removed when a successful assembly takes place). 
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The Debuggers 

Two families of debuggers are provided with the Macintosh 68000 
Development System. The first, and most powerful, is called MacDB. It 
is a two-machine debugger (either Macintosh or Lisa running MacWorks). 
The second, called MacsBug, works on a single Macintosh. 

MacDB and MacsBug have similar capabilities, but MacDB requires far 
less memory (and thus can be used to debug larger applications), it 
provides more information at any instant, and it's much easier to use. 

These debuggers are briefly described below. 


MacDB 


MacDB is the two-machine debugger. A small program called a Nub runs 
on the same machine as your application, MacDB runs on another machine, 
and the two machines are connected by a serial cable. The cable 
provided with the Development System is intended for debugging using 
two Macintoshes. The chapter on MacDB tells how to use MacDB with a 
Li s a . 

Several different Nubs are provided with the Development System. These 
various Nubs let you connect the machines using the printer port or the 
modem port, or allow you to debug your application using MacWorks. 

Features of MacDB include 

- Multiple memory display windows. Memory can be displayed as 
characters, words, long words, strings, or disassembled 
symbolically. System traps are displayed symbolically too. 

- Symbolic display of addresses. Memory addresses can be displayed 
in hexadecimal or as symbols , and you can use these symbols in 
expressions (for example, you can set the PC to START). 

- One or more register display windows. All registers and memory 
locations can be changed easily. 

- Multiple breakpoints can be set and cleared. 

- Instructions can be executed one at a time. 

- Memory search for patterns. 

- Special trace and break capability for system trap instructions. 

- Display and checking of the heap. 

- Display of linked lists. 
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Here is a typical MacDB display: 
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MacDB is described in Chapter 6. 



14 


Macintosh 68000 Development System 


Macs Bug 

The MacsBug debuggers are single-Macintosh debuggers. The different 
versions are for use on a 128K Macintosh, a 512K Macintosh, a Lisa 
running MacWorks , or a Macintosh connected to an external terminal. 

Features of MacsBug include 

- display and set bytes of memory 

- disassemble memory 

- display and set registers 

- set and clear up to eight breakpoints 

- tracing of single or multiple instructions 

- selective tracing of system traps 

- display and checking of the heap 
Here is a typical MacsBug display: 


MODS 12 s PC SUBQ-U *S1,D7 

PC=00H0DB 12 SR=00002000 

00 = 00000000 0 l = HGHFH2Hfl D2 = fl000678C D3=464F4248 
DH = 000 10000 05 = 00000007 D6 = 0000005C D7 = 0000000H 
fl0 = 000 15168 81 = 20010878 82 = 00012888 83 = 00012804 
84=00006228 85=00015688 86=00015156 87=000150F4 


MacsBug is described in Chapter 7. 
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The Resource Compiler 

The Resource Compiler, named RMaker , is a tool that translates a 
sequence of resource definitions in a text file into a file that 
contains those resources. 

Features of RMaker include 

- predefined resource types 

- definable resource types 

- the ability to include specific resources from other files, or 
entire resource files 

- visible display of the compilation process, with error reporting 
Here is a typical RMaker display: 
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RMaker is described in Chapter 8 
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System Definition Files 

Some of the most important tools available to assembly-language 
programmers are the system definition files. These files contain the 
values and addresses of the definitions available to the programmer. 

It's a good idea always to use these definition files and the symbolic 
names they contain, since some of these values may be subject to 
change . 

The system definition files provided with the development system are 


SysEqu.Txt 

SysEqu.D 

SysEquX.D 

ToolEqu .Txt 

ToolEqu.D 

ToolEquX.D 

QuickEqu.Txt 

QuickEqu.D 

QuickEquX.D 

FSEqu.Txt 

FSEqu.D 

PackEqu .Txt 

PrEqu.Txt 

SysErr • Txt 

Sys Traps .Txt 

ToolTraps .Txt 

QuickTraps .Txt 

PackMacs .Txt 

SANEMacs .Txt 

MacTraps .D 

MacDef s .Txt 


Low-level equates and globals 
Packed version of common ones 
Packed version of all 
Toolbox equates and globals 
Packed version of common ones 
Packed version of all 
QuickDraw equates and globals 
Packed version of common ones 
Packed version of all 
File system equates and globals 
Packed version of all 
Package equates and globals 
Printer equates and globals 
System error numbers 
Low-level traps 
Toolbox traps 
QuickDraw traps 
Package macros 

Numerics macros. See Inside Mac, 
Apple Numerics Manual (//030-0247-A) 
Packed version of SysTraps + 
ToolTraps + QuickTraps 
Macros translating Lisa-style 
directives into development system 
directives . 


Be sure that the symbols you use in your programs are identical to the 
symbols in these files. The .Txt files can be loaded into the Editor 
for viewing or printing. 

Packed symbol files are explained in the chapter on the Assembler. 




Chapter 2 
The Editor 
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About This Chapter 

This chapter describes the Editor, a general-purpose text editor. In 
the context of the Macintosh 68000 Development System, its primary uses 
are to enter and edit assembly-language programs, Linker control files, 
Executive control files, and RMaker input files. 


Files Required 

If you wish to move the Editor to another disk, you must move the file 
named Edit. If you wish to transfer from the Editor to the Assembler, 
the Linker, the Executive, or RMaker, those applications must be on the 
same disk. 


File Naming Conventions 

The following types of files are all created in the Editor, and should 
be given names with the designated extensions: 


Asm 

is 

Files 

is 


be 

Link 

is 

Job 

is 

R 

is 


recommended for assembly-language source programs. 

recommended for a file that contains a list of .Asm files to 
assembled • 

the extension for Linker control files, 
the extension for Executive control files, 
the extension for RMaker input files. 


These extensions indicate types of files that are used as inputs to the 
Assembler, the Linker, the Executive, and RMaker. Other extensions, 
such as .Txt, .Equ, and .D, can be used to classify other files used in 
your assemblies. 


Invoking the Editor 

There are several ways to use the Editor: 

- From the Finder, select and open the application named Edit. 

- From the Finder, select and open a text file created by the 
Editor. You can open up to four files simultaneously by selecting 
a group of them (by Shift-clicking them or dragging across 
multiple icons) before opening one of them. All files created 
using the Editor can be selected, as can listing and error files 
generated by the Assembler and Linker. 

- Choose Edit from the Transfer option of the Assembler, the Linker, 
the Executive, or RMaker. 
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- Call Edit from an Executive control file, as described in 
Chapter 5. 


About the Editor 


The Editor is a disk-based editor. Thus it f s capable of editing 
documents much larger than will fit in memory. When a document is 
open, you can use the scroll bars to move, both vertically and 
horizontally, through the document. The Editor brings new portions of 
the document into memory as they* re needed. 

To create a new document, choose New from the File menu. 

There are several ways to open existing documents: 

- To open an existing document, choose the uppermost Open command 
from the File menu. This opens a standard file selection box from 
which you select the file to be opened. All files with type 
’TEXT* can be opened from this menu. 

- You can also open files (including non-text files) by selecting 
the name of the file in an open document, and then choosing the 
other Open command from the File menu. 

- Finally, you can open a document by typing Command-K followed by 
the name of the file to be opened (including volume name if 
needed), and pressing Return. This technique is not listed in a 
menu, and it gives no visual feedback until the file is opened or 
not found. 

As many as four such documents can be on the desktop at a time. When 
you quit the Editor or transfer to another application, the Editor 
gives you a chance to save each document that has been altered. 


Editor Documents 


Editor documents consist of lines of text that are separated by Return 
characters. The Editor has no tools for manipulating or organizing 
pages, paragraphs, sentences, or pictures. 

When you type long lines of text, characters may be placed past the 
right edge of the window. To see these characters, use the horizontal 
scroll bar. It is possible to type a line longer than can be seen 
using the scroll bar. The text on such lines is not lost, but neither 
is it visible. To see the whole line, insert a Return into the middle 
of the line, breaking the line into smaller pieces. 

If you choose Show Invisibles from the Format menu, the invisible 
characters (Space, Tab, and Return) are replaced by visible symbols. 
Choose Hide Invisibles to restore normal display. 
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The Editor displays an entire document in text of a single size and 
font. The Monaco font, a monospaced font, is the default. Different 
documents on the desktop can have different fonts and font sizes. 


Editing 

Editing involves inserting text at the insertion point and removing, 
moving, copying, or replacing a selection. Any character or sequence 
of characters in a document can be selected and edited. 

You can replace the selection by typing or pasting. You can remove, 
move, or copy the selection using commands from the Edit menu or their 
keyboard equivalents. Cut or copied selections can be pasted into 
another place in the document, into another window (such as the Find or 
Change window), or into another document altogether. 

You can find and change text using the Find and Change commands in the 
Search menu. These commands search for a specified string starting at 
the current insertion point. If the string is found, it*s either 
selected and displayed or replaced. If not, a box is displayed to 
notify you that the string wasn’t found. When you choose Find, the 
currently selected string is used as the default string to find. You 
can close the Find or Change boxes by choosing Hide Find or Hide Change 
from the Search menu. 


Tabs and Alignment 

The Editor has several features that help organize programs visually. 
Tab stops allow you to align columns of text at regular intervals 
across the page; the Set Tabs command in the Format menu lets you set 
the distance between tab stops. 

The Auto Indent command in the Format menu lets you turn Auto Indent on 
and off. If Auto Indent is on, the insertion point Is automatically 
lined up with the leftmost edge of the previous line each time you 
press Return. To back the cursor up to the left edge of the screen, 
use the Backspace key. If Auto Indent is off, the insertion point is 
placed at the left margin. 

The Align command in the Edit menu aligns the left margins of all the 
lines in a selected block of text. The Move Left and Move Right 
commands, also in the Edit menu, move all the lines in a selected block 
of text one space left or right. If a proportional font is selected, 
the width of one space is usually quite small. The easiest way to move 
a block of text several spaces is to press the keyboard equivalent 
several times in succession. 
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Document Format 


Text created by the Editor is saved as a document file. A document 
file is a text-only file that can be used by other applications that 
use text -only files. For example, the Text Only option of MacWrite 
(see Save As in the MacWrite manual) creates text -only files that can 
be used by the Editor. 

A text-only file is a stream of ASCII characters. It contains Tab 
characters and Return characters, but no other formatting information. 


Printing Documents 

There are two ways to print documents: 

- From the Editor, choose the Print command in the File menu. This 
prints the current document and returns to the Editor. 

- From the Finder, select the documents you wish to print, then 
choose Print from the File menu. This prints the selected files 
and returns to the Finder. 

Printing from the Editor uses the current printing format. To set the 
printing format, choose Printing Format in the Editor’s File menu. 

After choosing this command, you are presented with a dialog box that 
lets you specify the size of paper you are using. Printing from the 
Finder displays the Printing Format box before the first document is 
printed. The settings you choose hold for all subsequent documents. 

A second dialog box, displayed for each document printed, lets you 
choose the print quality (High, Standard, or Draft), which pages to 
print, how many copies to print, and whether the paper is continuous or 
separate sheets. 

These two boxes are standard printing dialog boxes, and are discussed 
in some detail in the other manuals (for example, MacWrite). 








Chapter 3 
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About This Chapter 

This chapter describes the Macintosh Assembler. The Assembler 
translates one or more text files into files that contain relocatable 
code and symbol table information. Once all the portions of a program 
have been assembled, they can be linked together into an application. 
Even an application generated from a single source file must be linked 
before it becomes an executable application. 

The first part of this chapter describes the Assembler and how to use 
it. The second part of the chapter tells the syntax of statements 
accepted by the Assembler. The next part of the chapter is a reference 
for commands to the Assembler. 

This chapter doesn’t give extensive examples. An appendix contains a 
program listing that contains a variety of Assembler statements. Refer 
to this listing for examples of usage. 


Files Required 

If you wish to move the Assembler to a different disk, you must move 
the file Asm to that disk. If you wish to transfer from the Assembler 
to other applications, those applications must also be on the disk. 


File Naming Conventions 

Files used by the Assembler can be divided into two groups : those used 
as input to the Assembler, and those produced by the Assembler. The 
first two file extensions designate Assembler control files. .D files, 
described below, are also Assembler input files. 

.Asm is the recommended extension for assembly-language source 
programs. Text files of any name can be assembled. 

.Files is the extension for a file that contains a list of .Asm files 
to be separately assembled. 

The next file extension identifies files created by the PackSyms 
application. 

.D is the recommended extension for symbol files. They may 

be text files containing lists of equates, or packed symbol 
files; the assembler knows how to handle both. Refer to the 
section on packed symbol files at the end of this chapter. 

The final four file extensions are given by the Assembler to the files 
it creates. 

.Rel is the extension automatically assigned to every relocatable 
module generated by the Assembler. 
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• Lst designates listing files produced by the Assembler. 

•Err designates a file that contains the errors encountered during 
assembly of a program. 

•Sym designates a file of symbol table information. Refer to the 
.DUMP directive, below. 


Invoking the Assembler 

There are several ways to invoke the Assembler: 

- From the Finder, select from one to fpur files then open the 
application named Asm. The selected files are automatically 
assembled, then control returns to the Finder. 

- Choose Asm from the Transfer menu of another application. 

- Call Asm from an Executive control file, as described in 
Chapter 5. 


Using the Assembler 

The following sections contain an overview of the operation and 
features of the Assembler. They* re intended to provide enough 
information that you can use the Assembler menus easily once you've 
read this chapter. 


Assembler Source Files 


Assembler source files are text-only files, as created by the Editor. 
They should be named with the extension .Asm. A source file that 
contains a list of .Asm files to be separately assembled should be 
named with the extension .Files. 

A text-only source file consists of a series of lines of text, 
separated by Return characters. These lines may be blank lines, 
comment lines, assembly-language instructions, or instructions that 
control the Assembler (assembler directives). The exact format of 
source file lines is described in later sections. 





Using the Assembler 


27 


Selecting Listing Options 

There are two ways to select listing options for your program: by 
choosing commands in the Options menu, or by placing printing control 
directives into your source file. The printing control directives, 
described later in this chapter, override commands given from the 
Options menu. 

Before you actually assemble your program, you should select the type 
of program listing you want, if any. From the Options menu, you can 
choose No Listing, List to File, or List to Display. 

In the listings generated by the Assembler, addresses that aren't 
resolved until linking are displayed as lowercase x's. Certain 
instructions are marked by capital letters enclosed in parentheses. 

The following letters are used: 

P PC relative instruction 

R Relocatable instruction 

X Instruction will be modified if it crosses a 

segment boundary. The opcode displayed in the listing 
is not necessarily the final opcode. 

This menu also contains two options that let you choose what will be 
placed in the .Rel file produced by the Assembler. If Normal Output is 
chosen, the minimum amount of information is written to the .Rel file. 
If Verbose Output is chosen, information is written to the .Rel file 
that allows a Linker listing to be generated. If Verbose Output is 
turned on, the .Rel file is larger, the assembly takes longer, and 
linking takes longer. 


Selecting a Source File 

If the Assembler is selected from the Editor's Transfer menu while a 
document having the extension .Asm is the current window, that document 
is automatically assembled. When you do this, No Listing and Normal 
Output are always selected. 

Otherwise, choose Select File from the File menu; then select the 
source file from the dialog box. If the list of possible source files 
is disturbingly long, you can select Filter by Time in the File menu. 
When Filter by Time is on, only files that have been modified since 
last assembled are displayed in the dialog box. 

As the assembly proceeds, the name of the current source file is 
displayed in a box on the screen. Included files are displayed in 
parentheses; the number of parentheses indicates the level of nesting. 
Long file names may not fit entirely into the box. 
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Types of Source Files 

There are two types of files that can be assembled: .Asm files and 
•Files files. .Asm files contain lines of source and the names of 
other files to be included into that assembly. When you assemble a 
•Asm file, one .Rel file is produced. Here's a typical .Asm file: 


MDS2:My Program. Asm 


; File MyProgram . Asm 

XDEF Start 


ES 


I NCLUDE 
INCLUDE 


MacTraps.D 

NyEquates.D 


; This is where the main body of code goes. 
END 


EE 


reference for Linker 

use System Traps 
use my Equates 

Start of code for Linker 


End of code for Assembler 


Is 


•Files files contain names of separate assemblies to be performed. 

When you assemble a .Files file, multiple .Rel files are produced. For 
example, if you change a value in a .D file that’s used by three 
different library modules, you can reassemble all three modules using a 
file such as the following: 



In Search of Source Files 


The Assembler has a set of rules that determine where it looks for 
files to be assembled. These rules make use of the initial volume (the 
volume from which the Assembler was run) and the default volume (the 
volume that contains the file being assembled). They are as follows: 

- If the file name doesn’t include a volume name, the Assembler 
tries to open the file first on the default volume, and then on 
the initial volume. If the file is not found, an error is 
reported. 

- If the file name includes a volume name, the Assembler tries to 
open the file first on the specified volume, next on the default 
volume, and finally on the initial volume. If the file is not 
found, an error is reported. 
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- In the two steps above, if the file name has no extension, the 
Assembler tries to open filename • Asm before searching the next 
volume . 


What the Assembler Produces 


The assembled product is placed in a .Rel file. This file contains 
relocatable code and symbol table information and must be linked by the 
Linker before an executable application is produced. 

If List to File is chosen from the Options menu, an assembled listing 
is placed in a .Lst file. If List to Display is chosen, the assembled 
listing is instead displayed on the screen. To temporarily stop the 
listing, hold down the Command key while you type an S. The cursor 
blinks while listing is suspended. To resume the listing, type 
Command-S again. 

To stop the assembly permanently, click on the Stop button or hold down 
the Command key and type a period (.)• 

Errors encountered during assembly are written to a .Err file. 

Assembler errors are explained in an appendix. 


Assembler Syntax 

An Assembler source file consists of a series of lines of text, as 
entered in the Editor. These lines may be blank lines, comment lines, 
or instruction lines. 

Instruction lines contain some or all of the following: label, 
instruction (assembly-language or assembler directive), and comment 
fields. The following are valid instruction lines: 


=1 1 = 

E 

MDS2:Sample Instructions 

Lobe 1 

Lone_l abe 1 

MOUE 

#0,D0 

; Comments are nice. ^ 

1 ndented_too : 

BSR 

Labe 1 

j Indented labels haoe colons. 


AND 

D1,D2 

; Not all 1 ines haoe labels. . . jljiji 


DC . B 

'Hello' 


@1 

RTS 


; Some haoe local labels 

04: 

BSR 

@1 

j which may even be indented! ^ 

&MMMm 





The Assembler does not distinguish between uppercase and lowercase, 
except within strings. 
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Labels 


If a label does not begin in column 1, it must be followed by a colon. 
The first character in a label must be a letter, a period (.), or an 
underscore (_). Subsequent characters must be letters, numbers, 
periods, underscores, or dollar signs ($). Labels that are the same as 
directives or instructions are not allowed. 

The Assembler also supports local labels. A local label consists of an 
"at" symbol (@) followed by a decimal digit. If a local label is 
indented, it must be followed by a colon. 

The scope of a local label extends, in both directions, to the nearest 
non-local label. Any single local label can be used repeatedly within 
a file, but not within the scope of another instance of the same local 
label. 


Current Program Location 

The current program location is indicated by an asterisk (*). For 
example : 

BlkLen EQU BlkEnd-* ; Get length of following block 


Instructions 


An instruction can be a 68000 instruction, an assembler directive, or a 
macro instruction. 68000 instructions are described in the 68000 
Reference Manual. Assembler directives and macro instructions are 
explained below. If the instruction requires an operand, at least one 
space or tab separates the instruction and the operand. 


Comments 


Except when it appears within a string (see below), a semicolon marks 
the beginning of a comment. The semicolon and the remainder of the 
line are ignored by the Assembler. In addition, any line with an 
asterisk (*) in column 1 is treated as a comment. 


68000 Instruction Syntax 


The 68000 instructions and addressing modes are described in the 68000 
Reference Manual. The processor registers are named as follows: 


D0. .D7 
A0..A7 
A7 or SP 
SR 
CCR 


Data Registers 0 through 7 
Address Registers 0 through 7 
Stack Pointer 
Status Register 
Condition Code Register 
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PC Program Counter 

A group of address and data registers, used by the MOVEM command, is 
represented like this: 


Syntax 


Means 


D0-D1/A3 D0, Dl, and A3 

D2-D4/A1-A2/D7 D2 , D3 , D4, A1 , A2 , and D7 


Any combination of individual data and address registers and ranges of 
data and address registers can be used, in any order. 


Addressing Modes 


The syntax of the addressing modes is shown below. The notation An 
refers to address register A0 through A7 ; Dn refers to data register D0 
through D7 . Expressions, designated in the examples as Expr, are 
explained in the next section. 


Syntax 

Addressing mode 


An or Dn 

Register Direct 


(An) 

Register Indirect 


(An)+ 

Postincrement Register Indirect 

“( An) 

Predecrement Register Indirect 


Expr (An) 

Register Indirect with Offset 


Expr(An,An) 

Indexed Register Indirect with 

Offset 

Expr( An , Dn) 

Indexed Register Indirect with 

Offset 

Expr 

Absolute or Relative 


Expr (PC) 

Relative with Offset 


Expr(PC, An) 

Relative with Index and Offset 


Expr (PC , Dn) 

Relative with Index and Offset 


Expr(Dn) 

Relative with Index and Offset 

(see comment) 

//Expr 

Immediate 



Expr(Dn) is actually assembled as 
Expr-PC (PC,Dn) 

Both the sources and destinations of 68000 instructions use these 
addressing modes. The 68000 Reference Manual describes which 
addressing modes can be used with each instruction. Expr(Dn) can be 
used wherever Expr(PC,Dn) is allowed. 


32 Macintosh 68000 Development System 


Variants on 68000 Instructions 


Many 68000 instructions can be performed on operands of different 
sizes: byte, word, and long word. The 68000 Reference Manual lists 
the mnemonics for the 68000 instructions. To specify the length of the 
instruction, add the following extensions to the mnemonics: 


•B Operands are one byte long 

•W Operands are one word long (2 bytes) 

•L Operands are long words (4 bytes) 


For example : 


MOVE • L Test , A0 


; Move long word to A0 


If you don’t use a size extension, a default size is used (depending on 
the instruction). .B, .W, and .L are also used by the data allocation 
assembler directives described later in the chapter. 


Branch instructions have two forms: short and long. By default, the 
Assembler uses the long form. To specify a short branch, use the form: 


Bcc.S Short branch 


Jump instructions have two forms: word and long word. By default, the 
Assembler uses the word form. To specify a long jump, use the form: 

JMP . L Long j ump 

Broad jumps are not allowed. 

You can also specify the length of the index register in the indexed 
addressing modes. By default, the low word of the register is used as 
an index. For example, to specify the length in relative with index 
mode, use one of the following forms: 

Expr(PC ,Dn.W) 

Expr(PC,Dn.L) 

Note: The lengths that are allowed with particular instructions varies 
from instruction to instruction. 


Code Optimization 

Some code alteration or optimization is performed by the Assembler. 

ADD and SUB are changed to ADDQ and SUBQ, respectively, if the source 
operands are immediate (#) and within the range 1-8. 

The following table shows how the Assembler resolves jumps and branches 
to labels in the same segment and to labels in another segment. 
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Instruction 


Same segment 


Different segment 


JMP Label 
JSR Label 
BRA Label 
BRA. S Label 
BSR Label 
BSR.S Label 
Bcc Label 
Bcc.S Label 


JMP of f set (PC) 
JSR off set(PC) 
JMP off set (PC) 
BRA. S of f set(PC) 
JSR offset(PC) 
BSR.S of f set(PC) 
Bcc offset(PC) 
Bcc.S off set (PC) 


JMP of f set( A5) 
JSR of f set(A5) 
JMP of f set(A5) 
error 

JSR offset(A5) 
error 
error 
error 


When the destination is in another segment, the operation is performed 
as a positive offest to A5 (the location of the destinations jump 
table entry). 


Expressions 

Addressing modes and assembler directives often use arithmetic and 
logical expressions. Numbers and strings, and symbols that represent 
numbers, strings, and relocatable addresses, can all be used in 
expressions. 

Expressions are evaluated as 32-bit signed integers. 


Numbers 


Four types of numbers can be used in expressions: hexadecimal, 
decimal, octal, and binary. Here are examples: 


$3F0 

2001 

~765 

%1 1010011 


Hexadecimal numbers are preceded by a $ 
Decimal numbers are the default 
Octal numbers are preceded by a A 
Binary numbers are preceded by a % 


Strings 

A string is one or more ASCII characters enclosed in single quotes. To 
put a single quote in a string, use two consecutive single quotes. The 
exact format of a string that is allocated in memory is defined by the 
STRING__FORMAT directive. Refer to the STRING__FORMAT section for more 
details. Here are some sample strings: 


1 HELLO * 
’don 1 * t 1 
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Symbols 

A symbol is a name for a string, number, relocatable address, or macro. 
Strings and numbers are assigned to symbols by EQU and SET directives. 
Symbols are relocatable if they are created as labels, or if equated or 
set to labels. Macro symbols are set by macro definition statements. 

The first character in a symbol must be a letter (A-Z, a-z), a period 
(.), or an underscore (_)• Subsequent characters may be letters, 
numbers (0-9), periods, underscores, and dollar signs ($). 

All characters in a symbol are significant. 


Operations 

An operation is an action taken on one or more values. There are 
arithmetic, shift, and logical operations. They are: 


T yp e 

Operation 

Operator 

Comment 

Arithmetic 

Addition 

+ 



Subtraction 

- 



Multiplication 

* 



Division 

/ 

Integer result 


Negation 

- 


Shift 

Shift Right 

» 

Zeros shifted in 


Shift Left 

« 

Zeros shifted in 

Logical 

And 

& 



Or 

i 



Only addition and subtraction can be used on relocatable values. 


Precedence 

Multiple operators within an expression are evaluated in this order: 

1. Operations within parentheses (innermost first) 

2. Negation 

3. Shift operations 

4. Logical operations 

5. Multiplication and division 

6. Addition and subtraction 

Operators of the same precedence in an expression are evaluated from 
left to right. 
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Assembler Directives 


The following directives are described in this section: 
Assembly Control Directives 


INCLUDE Include source file 

STRING_FORMAT Set string format 

IF. .ELSE. .END IF Conditional assembly 

MACRO Define a macro 

•MACRO Define a Lisa-style macro 

END End of source 

•DUMP Create a .Sym file 

Symbol Definition Directives 


EQU 

SET 

REG 

.TRAP 


Assign a permanent value to a name 
Assign a temporary value to a name 
Assign a register list to a name 
Assign a name to a trap number 


Data Allocation Directives 


DC 

DS 

DCB 

.ALIGN 


Define constant 

Define storage 

Define constant block 

Align to word or long word boundary 


Linker Control Directives 


XDEF 

XREF 

RESOURCE 


Defined externally 

Referenced externally 

Begin resource type definition 


Printing Control Directives 


•NoList 
.Lis tTo File 
.ListToDisp 
.Verbose 
.No Verbose 


Turn off listing 

Turn on listing to file 

Turn on listing to the display 

Write information for Linker listing 

Turn off information for Linker listing 


The printing control directives are self-explanatory. Refer to the 
Selecting Listing Options section, earlier in the chapter, for more 
details on normal and verbose assembly. 

In the descriptions below, the terms label, value, expression, and 
comment are used as defined earlier in the chapter. [Optional fields 
are enclosed in square brackets.] 
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Assembly Control Directives 


INCLUDE - Include Source File 


Format: [label] INCLUDE Filename [comment] 

INCLUDE is used to combine multiple source files in a single assembly. 
INCLUDE causes Filename or Filename. Asm to be used as the source file 
instead of the current file. When END is encountered in the file, 
assembly returns to the file in which the INCLUDE was used. Filename 
may contain a volume name. Here is a sample file that uses INCLUDE: 


; File MyProgram . Asm 

MDS2:MyProgram.flsm 

£ 

XDEF 

Start 

; reference for Linker 

(Pi 

INCLUDE 

MacTraps.D 

; use System Traps 


1 NCLUDE 

MyEquates . D 

; use my Equates 


Start 


; Start of code for Linker 


; This is where the main body of code goes. 



END 


; End of code for Assembler 

<> 

ou 


■in wmmmmmrnm 

a 


INCLUDE directives can be nested up to five levels deep. When an 
assembly is taking place, the name of the current input file is 
displayed. Included files are displayed in parentheses; the number of 
parentheses reflects the number of levels of nesting. 


STRING FORMAT - Set String Format 

Format: [label] STRING__FORMAT value 

This directive determines the format of the strings that the Assembler 
generates. 

Strings used as arguments to PEA or LEA instructions are allocated just 
after the code. If STRING_FORMAT is not used in the program, these 
strings are preceded by a length byte. Otherwise, bit 0 of the last 
STRING__FORMAT in the program determines the format of these strings. 

Use these values : 

STRING_FORMAT = 0 Text followed by a 0 byte 

STRING_FORMAT = 1 Text preceded by a length byte 

Strings used as arguments to DC.B, DC, DC.W, and DC.L are allocated at 
the point at which they are defined. By default, they are written 
without trailing 0 bytes or leading length bytes. Bit 1 of 
STRING__FORMAT is used to determine the format of these strings. Use 
these values: 
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STRING_FORMAT = 0 Text with no length or trailing 0 byte 

STRING_FORMAT = 2 Text preceded by a length byte 

With the DC.B directive, no padding of strings ever takes place. With 
the DC (word), DC.W, and DC.L directives, zeros are placed before the 
string to align the string to the nearest word boundary and at the end 
to fill to the nearest word or long word boundary. 

The format of both types of strings is set by each STRING_FORMAT 
statement used. For example, the statement 

STRING FORMAT = 3 


causes all strings to be preceded by a length byte. Here are some 
examples of the use of strings. The first two do not cause special 
string memory to be allocated; the next two do. 

MOVE # * JUNK 1 , D0 ; Move ASCII *JUNK* into D0 

SUB //*A*-*a*,D0 ; Use , A , - , a* as a constant 

PEA *NewString* ; Push address of *NewString* 

; *NewString* placed at end of code; 
; form determined by STRING_FORMAT 
DC.L *Try Again* ; Place string data in code 

; using current STRING_FORMAT 


IF. .ELSE. .ENDIF - Conditional Assembly 


Format : 

[label] 

IF condition 

[comment] 



[ELSE 

comment ] 



ENDIF 

[comment] 


IF. .ELSE. .ENDIF are used to include or exclude sections of code at 
assembly time based on the value of a condition. 

IF specifies to the Assembler that the subsequent block of code should 
be assembled if and only if the condition following IF is true. The 
block of code is terminated by an ELSE (if there is one), or an ENDIF. 
If ELSE is used, it specifies to the Assembler that the subsequent 
block of code should be assembled if and only if the condition 
following IF is false. An ELSE block is terminated ENDIF. 

A condition is true if it evaluates to a nonzero value; otherwise it is 
false. Two types of conditions can be used: expressions or the 
relationship between two expressions. Expressions cannot be 
relocatable. Non-string expressions can be compared using >, <, >= , 

<= , =, and <>. Strings can be tested for equality using = and <>. 
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Conditionals can be nested. 


MACRO - Macintosh-Style Macros 

When your source is assembled, each macro call is replaced by the text 
(usually a list of instructions) defined as that macro. The parameters 
used in the macro call are placed, character-f or-character , at 
designated positions in the list of instructions. All characters 
except Return and comma (,) can be passed to a macro in the parameter 
list • 

Macros can be nested up to eight levels deep. 

Here is the format of a Macintosh-style macro definition: 

Format: MACRO name [argument( s ) ] = 

macro body 


A macro definition is delimited by the MACRO directive and a vertical 
bar (|). It consists of a macro name, an optional list of arguments, 
followed by ,, * H , and a macro body that makes use of those arguments. 

The macro body is simply text. This text is exactly like normal source 
text, but with one exception: Arguments, which are to be replaced by 
parameters specified in the macro call, are enclosed in braces ({}). 

Each argument has a unique symbol within the macro. Multiple arguments 
are separated by commas, with no intervening spaces. 

For example : 

MACRO MODS R1,R2 

DIVS {R1},{R2} 

SWAP {R2 } 


The macro MODS has two arguments, R1 and R2 . It can be called, for 
example, with the macro call: 

MODS D1,D2 

When the program is assembled, this call causes the following 
instructions to be placed in the code: 

DIVS D1,D2 

SWAP D2 

Macro calls are not necessarily entire instructions; they can be used 
anywhere. The following example shows a macro that is used as part of 
an instruction: 

MACRO SegRef LabelName = {LabelName } ( A5 ) | 
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SegRef can be used like this: 

LEA SegRef Label, A0 

It causes the following instruction to be placed in the code: 

LEA Label(A5),A0 

It is possible for a macro to use just part of a string received as an 
argument. A partial argument is designated by following the argument’s 
name with |N:M where N is the position in the string of the first 
character to be used (0 is the first position), and M is the number of 
characters to use. For example, if you define 

MACRO LAST2 STR = DC.B 1 { STR | 2 : 2 } f | 

Then using the macro 

LAST 2 ABCD 

is equivalent to using the instruction 
DC.B ’CD 1 


.MACRO .ENDM - Lisa-Style Macros 


Format: .MACRO name [argument( s ) ] [comment] 

macro body 

•ENDM [comment] 

A Lisa-style macro is delimited by the .MACRO and .ENDM directives. It 
consists of a macro name and a macro body that contains optional 
arguments. When the Assembler encounters the macro name, it 
substitutes the macro body for the macro name in the assembly text. 
Wherever an argument, %n, occurs in the macro body (n is a digit from 1 
through 9), the text of the nth parameter is substituted. Null strings 
are substituted for omitted parameters. 

Here is a sample Lisa-style macro: 

.MACRO Help 

MOVE %1,D0 

ADD D0,%2 

.ENDM 

When this macro is called by the instruction 

Help Me, Rhonda 

The following text is assembled: 


; get first parameter 
; and add it to second parameter 
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MOVE Me ,D0 

ADD D0, Rhonda 


END - End of Source 


Format: [label] END 

The end of a source file may optionally be indicated by an END 
directive. When END is used, all subsequent lines in the file are 
ignored by the Assembler. If END is omitted, the physical end of file 
indicates the end of a source file. 


. DUMP - Make .Sym File 

Format: [label] .DUMP Filename 

The .DUMP directive instructs the Assembler to create a symbol table 
(.Sym) file and to place it in the file named Filename . Sym. .Sym files 
are used by PackSyms to create packed symbol files, as explained at the 
end of the chapter. 


Symbol Definition Directives 


EQU - Assign Permanent Value 

Format: symbol EQU expression [comments] 

This directive assigns an expression to the specified symbol. The 
symbol cannot be redefined later in the program. The expression can be 
any valid operand in any addressing mode. It may contain undefined 
symbols, register references, and so on. For example, 

LookTable2 EQU Table2(A0) 

is a legal form, as long as LookTable is always used in the proper 
context. The expression can’t contain more than one undefined 
identifier. For example, although 

A EQU B 

is a valid statement, 

A EQU B-C 


is not 
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SET - Assign Temporary Value 

Format: symbol SET expression [comments] 

Like EQU, this directive assigns a value to the specified symbol. 
However, the symbol can later be redefined by other SET directives. 
The expression is the same as an expression used with EQU, above. 


REG ~ Assign Register List 

Format: symbol REG register list [comments] 


This directive assigns a register list to the specified symbol. The 
register list represented by the symbol can then be used in the MOVEM 
command. The syntax of a register list is defined in the Assembler 
Syntax section of this chapter. 


.TRAP - Assign Name to Trap Number 

Format: [label] .TRAP name $Axxx 

This directive assigns a name to the specified trap number so that the 
name can be subsequently used as a 68000 instruction. The name must be 
a valid symbol, and the trap number must have a corresponding entry in 
the trap dispatch table. This directive is primarily used in the 
system trap files. 


Data Allocation Directives 


All .Rel files created by the Assembler have two parts: the code area 
and the data area. Everything in a source file that produces a value 
is placed into the code area. Code areas are then loaded into the 
proper code segment by the Linker. Data areas defined by DS directives 
are combined into a global block. This block is located by the Linker 
downward from -$100(A5). 

This a good way to create permanent storage for handles. 

The starting address of the global block can be set using the /GLOBAL 
Linker directive. 


DC - Define Constant 


Format : 

[label] 

DC . B 

value(s) 

[comment] 


[label] 

DC 

value(s) 

[comment ] 


[label] 

DC.W 

value(s) 

[comment] 


[label] 

DC.L 

value (s ) 

[comment] 
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The DC directives place data in the code area of the program. These 
four forms of the DC directive generate data that is byte aligned 
(DC.B), word aligned (DC or DC.W), and long word aligned (DC.L). 

A value is an expression that evaluates to the data to be stored. 
Multiple values are separated by commas. 

With the DC.B directive, no padding of strings ever takes place. With 
the DC (word), DC.W, and DC.L directives, zeros are placed before the 
string to align the string on a word boundary and at the end to fill to 
the nearest word or long word boundary. The format of the string is 
determined by the STRING_FORMAT directive. 


PS - Define Storage 


Format : 

[label] 

DS.B 

length 

[comment ] 


[label] 

DS 

length 

[comment ] 


[label] 

DS.W 

length 

[comment ] 


[label] 

DS.L 

length 

[comment ] 


The DS directive is used to reserve memory locations. The length is an 
expression specifying the number of bytes, words, or long words to be 
reserved. The expression may not contain values that are not yet 
defined • 

These memory locations are always located relative to A5. When you 
reference a label defined using DS, you must explicitly reference A5. 
For example : 

DS.L MenuHandle ; reserve handle space 

MOVE.L ( SP)+, MenuHandle (A5) ; get handle from stack 

Word alignment is enforced for DS (word), DS.W, and DS.L. Labels 
always refer to the first address in the defined area after alignment. 


DCB - Define Constant Block 


Format : 


[label] 

[label] 

[label] 

[label] 


DCB.B length, value 
DCB length, value 
DCB.W length, value 
DCB.L length, value 


[comment] 
[comment ] 
[comment ] 
[comment] 


The DCB directive is used to reserve blocks of memory, at the current 
position in the program, that are to be initialized to a certain value 
Length specifies the number of bytes (DCB.B), words (DCB or DCB.W), or 
long words (DCB.L) in the block. The expression specifying the length 
may not contain forward references. Value specifies the initial value 
of the storage units in the block; it may contain forward references. 


Word alignment is enforced for DCB, DCB.W, and DCB.L. Labels always 
refer to the first address in the defined area after alignment. 
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. ALIGN - Align to Word or Long Word Boundary 

Format: [label] .ALIGN value [comment] 

This directive causes the proper number of bytes to be reserved such 
that the next statement is aligned on a byte, word, or long word. 

The value is an expression that determines the alignment, as shown 
below: 


value = 1 
value = 2 
value = 4 


Align to byte boundary (No-op) 
Align to word boundary 
Align to long word boundary 


Linker Control Directives 


The XDEF and XREF directives should be used to specify all routines 
that are either used or defined externally. These directives allow 
independently assembled modules to share routines with one another. 


XDEF - External Definition 


Format: XDEF symbol(s) [comment] 

XDEF tells the Assembler that the specified symbols, defined in the 
current module, are used externally. The Assembler then generates 
information that can be used by the Linker to share these symbols with 
other code modules. Modules that wish to use the symbol must use XREF 
to gain access to it. Multiple symbols are separated by commas. 

The label used as the starting label in a linker control file must 
always be referenced using XDEF. 

Only addresses that are referenced by XDEF are placed in the .Map file. 
Thus you should use XDEF for each routine or label that you wish to be 
symbolically displayed by MacDB. 


XREF - External Reference 


Format: XREF symbol(s) [comment] 

XREF tells the Assembler that the specified symbols, used in the 
current module, are defined in other modules. A code module must use 
XDEF for each routine or label used by other modules. The Assembler 
then generates information that can be used by the Linker to connect 
the real symbols to the module. Multiple symbols are separated by 
commas • 

If you use XREF with a symbol that is also defined within the module, 
the Assembler gives you a warning and allows the XREF. 
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RESOURCE - Begin Resource Type Definition 

Format: RESOURCE type ID [name [attr] ] 

The RESOURCE directive is explained in full detail in the chapter on 
the Linker* This directive should not be used in the main portion of 
your application; it should only be used in files that are linked after 
the /RESOURCES Linker directive. 

The type is an expression that should evaluate to a four-character 
string. It can be one of the standard resource types or a new type 
that you are defining. The resource ID is a nonrelocatable integer 
expression. The specified integer must be unique within the specified 
type. The optional name is a string that must be unique within that 
resource type. The attr field is a nonrelocatable integer that is used 
to specify the value of the resource* s attribute byte. 

Note that the parameters are not separated by commas. 


Creating Packed Symbol Files 

The PackSyms program lets you compress the symbols used by your program 
into a packed form. This packed symbol file can then be used as input 
to the Assembler. Using packed symbol files saves disk space and 
memory space, and makes assembly faster. 

The first step in generating a packed symbol file is to use the .DUMP 
assembler directive to place the application * s symbols in a • Syra file. 
Here is a sample file that creates a .Sym file: 


= M= = 

=— ^ MDS2:MyEquates.Rsm — 1 

; File MyEquates . Asm 

1 NCLUDE 

SysEqu . D 

o 

; Vou can INCLUDE packed files 

1 NCLUDE 

Too 1 Equ . D 

; as well as text files to create jjjiji 

1 NCLUDE 

MyEquates . Txt 

; one big packed symbol file. 

.DUMP 

MyEquates 

; Now dump to MyEquates . Sym . 

END 


; End of source. liiliL 

o 





When assembled, this file generates the file MyEquates . Sym. .Sym files 
are text files that can be edited using the Editor. 

Once you have created a .Sym file, you are ready to run PackSyms. Its 
menu bar contains three menus: Transfer, File, and Options. First 
choose the display option you want from the Options menu. Next, choose 
Select Input from the File menu, and choose the .Sym file to be added 
to the packed symbol file. Repeat this step for each .Sym file to be 
added. When all desired .Sym files have been added, choose Select 
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Output from the File menu, and enter the name of the file to contain 
the packed symbol information. This file should have the extension .D. 

The new .D file can then be used in an Assembler input file. For 
example : 


MDS2:Myflpplication.flsm 


File MyAppI i cat ion. Asm 

I NCLUDE 
I NCLUDE 
I NCLUDE 
END 


MyEquates . D 
Module 1 .Asm 
Modu I e2. Asm 


; get packed symbols 
; and code 

; end of assembly 


M. 




0 


a 


About Packed Symbol Files 

The Assembler identifies packed symbol files by type and not by 
extension. For example, you can use a text file name MyEquates. D 
during program development and replace it with a packed symbol file 
when the symbols stop changing. This replacement is entirely 
transparent to the .Asm file, it speeds up assembly, and it frees up 
disk space. 








Chapter 4 
The Linker 
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About This Chapter 

This chapter describes the Linker, the program that takes .Rel files 
produced by the Assembler and connects them into an application. 

The first part of this chapter describes the Linker. The rest of the 
chapter describes the commands accepted by the Linker. 


Files Required 

If you wish to move the Linker to a different disk, you must move the 
file named Link. If you wish to transfer from the Linker to the 
Editor, the Assembler, the Executive, or RMaker , those applications 
must also be on the disk. 


File Naming Conventions 


.Link is the required extension for Linker control files. Linker 
control files are text -only files, as created by the Editor. 

•Map is the symbol table file, used primarily by MacDB. If 

a Linker listing was requested, it is also in this file. 

•LErr indicates a file that contains the errors encountered during 
the linking process. 

The executable object file (an application) formed by the Linker has no 

extension. 


The Structure of a Macintosh Application 

This section contains information from the Inside Macintosh chapter 
with the same name. Please refer to that chapter for more details. 

Macintosh files have two forks: a resource fork and a data fork. The 
resource fork contains a number of resources; the data fork may contain 
anything. The simplest application created by the Linker has two 
resources in the resource fork, and nothing in the data fork. The 
first resource is the ’CODE * resource with ID 0. By definition, this 
resource contains the jump table and information about the 
application’s use of parameter and global space. The second resource 
is the ’CODE’ resource with ID 1 . It contains the application’s first 
code segment. 

More complicated applications can be created using Linker commands, 
described below. With these commands, you can add code segments and 
other resources to the resource fork of the file, or you can place 
information in the data fork of the file. You can also set the 
directory information that specifies the file’s type and creator. 
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Invoking the Linker 

There are several ways to invoke the Linker : 

- From the Finder, select and open the application named Link. 

- Choose Link from the Transfer option of another application. 

- Call Link from an Executive control file, as described in 
Chapter 5. 


The Linker Control File 


The Linker is controlled by a Linker control file with the .Link 
extension. This file specifies the names of the files to be linked 
together, how the program should be segmented, listing options, and 
various parameters of the .Map file. 

Each command in a Linker control file must be on a separate line. 
Blank lines in the file are ignored. 


Linker Commands 


The following sections describe the commands that can be used in Linker 
control files. 


filename .Re 1 
filename 

! label 


< 

[ 

] 

( 

) 

$ 

/Verbose 


The next file to link is the file named f ilename .Rel . 
The next file to link is the file named filename .Rel . 

Make label the starting location for the program 
(may only be used once). If label is omitted, the 
program is assumed to begin with location 0 of the 
first file. You must use XDEF to make label 
external • 

Start a new segment. 

Turn on code listing to .Map file. 

Turn off code listing to .Map file. 

Turn on listing of local labels to .Map file. 

Turn off listing of local labels to .Map file. 

End of Linker control file. 

Turn on verbose linker output. This option turns 
on listing of linked code. 
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/NoVerbose 
/UndefOK 
/No Unde f 
/Type 
/Bundle 

/Globals value 
/Output filename 
/Resources 
/ Data 


Turn off verbose linker output. 

Give warnings only for undefined symbols. 

Give fatal errors for undefined symbols. 

Set type and creator bytes in file directory. 
Set bundle bit in file directory. 

Set the start of the global space to value(A5). 
Specify the name of the output file. 

Begin resource portion of application. 

Begin data portion of application. 


Setting the File's Type and Creator 

Each file's directory contains eight bytes that specify the file's type 
('APPL', 'TEXT', and so on) and creator ('MPNT', 'EDIT', and so on), 
and a bit that specifies to the Finder that the file uses the Bundle 
resource (type 'BNDL') described in Inside Macintosh . An application 
must have the type 'APPL' if it is to be launched by the Finder when 
you open it. An application's creator bytes should be the signature 
for that application. The creator bytes for a file that isn't an 
application should be the signature of the application to be launched 
when you open that file. 

For example, the Editor has the type 'APPL' and the creator 'EDIT', and 
documents created by the Editor have the type 'TEXT' and the creator 
'EDIT'. When you open the Editor or a document created by the Editor, 
the Editor is launched. 

( By the Way ) 

Application signature bytes, and type bytes for other 
files, must be assigned (or approved) by Apple Technical 
Support . 

To use the /Type command, follow the command by two four-byte strings, 
as in 


/TYPE 'APPL' 'MYAP* 

If the creator string is omitted, it is set to 0. If this command is 
not used, the type is set to 'APPL'. When an error occurs during 
linking, the file is given the creator 'BADF'. This prevents it from 
being launched by the Finder. Type strings are case sensitive. 

To set the bundle bit in the file's directory entry, place the /Bundle 
command in your Linker source. 
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Setting the Global Storage Area 

Data storage allocated by the DS assembler directive is normally placed 
downward from -$100(A5). QuickDraw globals are placed in the area 
immediately below A5. The /Globals directive lets you change the 
address of the global storage area. For example, to place data at 
-$200(A5) instead, use the directive: 

/Globals -$200 

The value used to specify the address must be negative. 


Specifying the Output File 

The /Output directive specifies to the Linker the name of the file in 
which it places its output. This file can be an application file, a 
resource file, or some other type of file. Note that /Output specifies 
the name of a single output file, regardless of its position in the 
Linker control file. 

An example of a Linker control file is given below. A more complex 
example is given later in the chapter. 


MDS2:NemProgram.Link 


; File NewProgram .Link 
! Start 

/Output TestProgram 
[ 

MyProgram 

Parser 

Dispatcher 


; starting location of the appl i cat ion 

j output file is TestProgram 

; listing on (assemble w /verbose on) 

; first file is MyProgram . Re I 
; second file is Parser.Rel 
; third file is D i spatcher . Re I 

; done I inking. . . 


tel {iilllllllj 


k>l 


S' 


a 


Adding Resources and Data to the Code 

The Linker provides directives that allow you to add resources to the 
resource fork and to place data in the data fork of the file. 
Alternately, you can use the Resource Compiler to generate the resource 
portion of your application, as explained in the chapter on RMaker. 

The code, resource, and data portions of an application must be given 
to the Linker separately, and in that order. The beginning of the 
resource portion is indicated by the /Resources directive, and the 
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beginning of the data portion is indicated by the /Data directive. 
Here is a sample Linker control file that uses these directives to 
place some resources after the code in the resource fork of the file 
and to place data in the data fork of the file : 


; Fi le Big. Link 

' MDS2:Bi 9 Link == 


H 

! Start 
] 

; starting location of the appl i cat ion 
; 1 i sting off 



CodeModu 1 e 1 
CodeModu 1 e2 

< 

CodeModu 1 e3 

/Resources 
RsrcModu 1 e 1 
RsrcModu 1 e2 

/Data 

DataModu 1 e 1 

; code modules are linked first 

; this module is a separate segment 

; resource modules are 1 inked next 

; data modules are linked last 



$ 

ouiiBiieieiii 

; done 1 inking 

SSSHPi 

a 

a 


All files linked by the Linker must be .Rel files, as generated by the 
Assembler or RMaker. Resource .Rel files have a strictly defined 
format; data .Rel files can contain anything. 

Each resource in an Assembler source file should be initiated with the 
RESOURCE assembler directive. The parameters are the resource type, 
the resource ID, an optional resource name, and an optional attribute 
byte. For example, to begin a menu resource with an ID of 4 and no 
name, use the directive 

RESOURCE ’MENU* 4 

It*s a good idea to use a '.ALIGN 2' directive before the resource to 
avoid undesired padding bytes at the beginning of the resource. 

External symbols may not be defined in files linked following the 
/Resources directive. /Resources should be followed by the data 
contained in the resource. In the case of certain resources, such as 
'DRVR' resources, the data in the resource is actually code. 

An effective way to define resources is to create a macro for each 
resource type. For example: 
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MACRO DEFINEMENU NAME, ID , FLAGS = 


.ALIGN 

2 


RESOURCE 

'MENU' {ID} 


DC .W 

{ID} 

; Menu ID 

DC.W 

$0 

;Menu width 

DC . W 

$0 

;Menu height 

DC.L 

$0 

;Menu definition procedure 

DC . L 

{FLAGS} 

; Enable flags 

DC .B 

1 

{NAME} 


MACRO MENUITEM 

TEXT, ICON .KEY = 


DC . B 

{TEXT} 


DC . B 

{ICON} 


DC . B 

{KEY} 


DC . B 

$0 

;Marking character 

DC . B 

$0 

; Style 


Then, when defining a menu, you could use calls such as the following 


DEFINEMENU transfer*, Launch_Menu_ID+Edit_ID , $FFFFFFED 


MENUITEM 

1 Edit 1 , 

, > Y- 

0,0 

MENUITEM 

i _ i 

» 

0,0 

MENUITEM 

’Asm 1 , 

0,0 

MENUITEM 

* Link * , 

0,0 

MENUITEM 

“ > 

0,0 

MENUITEM 

’Exec * , 

0,0 

DC.B 0 


;end of items 


Refer to Inside Macintosh for the formats of the different types of 


resources . 
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About This Chapter 

This chapter describes the Executive, an application that accepts a 
text file as input, and uses the commands in the text file to launch 
other applications. 


Files Required 

If you wish to move the Executive to a different disk, you must move 
the file named Exec. If you wish to transfer from the Executive to the 
Linker, the Editor, the Assembler, or RMaker, those applications must 
also be on the disk. 


File Naming Conventions 

•Job is the required extension for Executive control files. Only 
files with this extension can be selected using the Open Job 
File option in Exec's File menu. 

Invoking the Executive 

There are several ways to invoke the Executive: 

- From the Finder, choose and open the application named Exec. 

- Choose Exec from the Transfer menu of another application. 

- Call Exec from an Executive control file. 


The Executive Control File 


The Executive is controlled by an Executive control file with the .Job 
extension. This file specifies the names of applications to be run and 
what to do when the applications finish. 

An Executive control file consists of a sequence of lines; each line 
invokes an application. A line consists of four fields: the 
application to be called, a string to be passed to the application as 
input (usually a filename), the application to be called if the 
original application is successfully completed (usually Exec), and the 
application to be called if an error occurs in the original 
application. Each field must be separated from the next by exactly one 
Tab character. 
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Here is a sample Executive control file: 

Asm Foo. Files Exec Edit 

Link Foo. Link Exec Edit 

It assembles the files specified in Foo. Files, and, if successful, 
links the files specified in Foo. Link. If either the assembly or the 
linking fails, the Editor is invoked, and the Exec terminates, but can 
be restarted or continued from the Execute menu. 


Using the Executive 

When you are using the Executive, all applications must be on the 
startup volume, which must not be write-protected. In addition, the 
volume containing the .Job file is established as the default volume 
for files used by the application. Use volume names for files that 
aren't on the same volume as the .Job file. 

The default name for the Exec file is Exec. Job; it must be on the 
startup volume. To use Exec. Job, choose the command Execute Exec. Job 
from the Execute menu. 

If you give your Exec file another name, you can place it on other 
volumes. Exec files must always have the extension .Job. To use a 
•Job file, select it using the Open Job File command in the File menu. 

If an error occurs while an Exec file is running, a temporary file is 
left on the disk. This file allows you to resume the Executive, 
presumably after correcting the error. If you choose Resume from the 
Execute menu, the Exec file starts at the line following the one in 
which the error occurred. If you choose Resume and Re-do Last, the 
Exec file starts at the line in which the error occurred. 

You can stop an Exec file by typing a period while holding down the 
Command key. 



Chapter 6 

The MacDB Debugger 
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About This Chapter 

This chapter describes MacDB, an application that helps you debug 
Macintosh applications. MacDB provides sophisticated debugging 
capabilities at the machine -language level. Its features include 

- Multiple memory display windows. Memory can be displayed in 
multiple windows as characters, words, long words or strings, or 
it can be disassembled symbolically. System traps are displayed 
symbolically too. 

- Versatile memory address display. Addresses can be displayed in 
hexadecimal or as symbols , and you can use these symbols in 
expressions (for example, you can set the PC to START). 

- One or more register display windows. All registers and memory 
locations can be changed easily. 

- Multiple breakpoints can be set and cleared. 

- Instructions can be executed one at a time. 

- Memory search for patterns. 

- Special trace and break capability for system trap instructions. 

- Display and checking of the heap. 

- Display of linked lists. 


Setting Up MacDB 

The use of MacDB requires two Macintoshes (or a Lisa running MacWorks 
and a Macintosh) that are connected together: The target machine runs 
the program to be debugged, and the debug machine runs MacDB. 

If you are using two Macintoshes, connect the two machines together 
using the cable supplied with the Development System. The debug 
machine must be connected at port B, the printer port. The target 
Macintosh can be connected at either port. 

If you are connecting a Macintosh to a Lisa, use a Macintosh 
ImageWriter cable. The debug machine must be connected at port B, the 
printer port. If the target machine is the Lisa, it too must be 
connected at port B. The cable connections required by the Macintosh 
and the Lisa are shown in an appendix. 

Next, run one of the Nub applications on the target machine. Use 
MacNub A if the target Macintosh is connected by port A, and MacNub B 
if it is connected by port B. Use WorksNub if the program to be 
debugged is running on a Lisa under MacWorks. 
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Running a Nub installs and initializes a small program in the system 
heap of the target machine. Now run the application to be debugged. 

On the debug machine, run the MacDB application. 

It is helpful to actually run MacDB while you read the following 
sections. If you have two machines, you can try out MacDB by running 
the Window sample program application on the target machine. 

One useful technique is to make the Nub the target machine*s startup 
application using the Set Startup command in the Finder* s Special menu. 
This guarantees that the Nub is already there just in case your 
application bombs. 


Theory of Operation 

MacNub is a small program that runs in the system heap of the target 
machine. When run, it places itself in the system heap, puts pointers 
to itself in most of the hardware exception vectors in $0000 through 
$00FF, then returns control to the Finder. It then remains dormant 
until one of "its" exceptions occurs. Here is the list of exceptions 
to which MacNub responds : 


Exception number 


Assignment 


2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

24 

28 

29 

30 

31 
46 


Bus Error 
Address Error 
Illegal Instruction 
Zero Divide 
CHK Instruction 
TRAPV Instruction 
Privilege Violation 
Trace 

Line 1010 Emulator 
Line 1111 Emulator 
Spurious Interrupts 
Level 4 Interrupts 
Level 5 Interrupts 
Level 6 Interrupts 
Level 7 Interrupts 
Trap $E (breakpoints) 


68000 exception processing is described in the 68000 Reference Manual. 


The simplest way to generate an exception on the target machine is to 
press the interrupt button (the rear button on the programmer *s 
switch). Another good technique is to place the line 

DC.W $FF01 ;generate a line $F exception 

at the beginning of your program, or wherever you want MacDB to first 
get control. (Actually any value $F000 through $FFFF can be used.) 
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When one of these exception events occurs in the target machine, the 
Nub gets control and sends an interrupt to the debug machine. The 
debug machine (if running MacDB) displays a box that lets you select 
whether to Debug or Proceed. 

If you select Proceed, the target machine continues execution at the 
current value of the PC. If the PC points to an instruction that 
caused an exception (such as the $FF01 used above), the exception will 
happen again. You must manually advance the PC before selecting 
Proceed • 

If you choose Debug, MacDB requests from the target machine all the 
information necessary to update its windows. Normal operation of the 
target machine is suspended until you choose Proceed from the Run menu. 


The MacDB Windows 


Here is a typical MacDB display, and a brief description of the default 
contents of each of the windows. 



Debug Run Bkpts Window format Symbols 


Registers 



DO 

_ 

HiTiTri 

TT»T«T»1 

D 1 

a 

oooc* 

r00R8 

D2 

= 

FFFF 

0000 

D3 

= 

6001 

0024 

04 

= 

0000 

0024 

05 

= 

0000 

00FF 

06 

ss 

0000 

FFFF 

D7 

= 

FFFF 

FF03 

R0 

= 

0001 

R6D4 

fll 

= 

0000 

5RC8 

R2 

= 

0000 

5RB6 

R3 

= 

0001 

R644 

R4 

= 

0000 

557R 

R5 

= 

0001 

R6D8 

R6 

= 

0001 

R520 

R7 

= 

0001 

R41E 

PC 

= 

0000 

■tx 

m 
i o 
m 

SR 

B 

2000 

mM 



JSR $34<PC) 

JSR $4E<PC ) 

JSR $56 (PC > 

DrauiMenuBar 
JSR $86 (PC) 

JSR $9E(PC> 

MOUE.L $5D4(PC> 

TEIdle 

SystemTask 

CLR -(R7 ) 1R41E 

MO YE «$FFFF,-(R7> 1R41EI 


< IN ITT 
(IHITf 
(SETUF 

(SETUF 

(SETUF 

(R7> 


PER $2EE(PC > 
GetNextEvent 
MOUE (R7)+,D0 
BEQ.S *$-18 
JSR $9C(PC ) 
BEQ.S *$- IE 
RTS 


(RB0U7| 

1R41E 

(START! 

(SETUF 

(START 


INITMRNRGERS: PER $-4(R5) 1R6D4 


I N I TMRNR+4 
INITMRNR+6 
I N I TMRNfl+8 
I N I TMRNR+E 
I N I TMRNR+ 10 
I N I TMRNR+ 12 


Ini tGraf 
Ini tFont 
MOUE.L #$FFFF,D0 
FlushEvents 
I n i tU i ndow 
Ini tMenus 


Breakpoints 


3§ 


7> 1R41E: 
1R422: 
1R426 : 
1R42R : 
1R42E : 
1R432: 
1R436: 
1R43R: 
1R43E : 
1R442 : 
1R446 : 


0000 

0000 

FFFF 

6001 

0000 

0000 

0000 

FFFF 

0000 

0001 

0000 


0000 
00R8 
0000 
0024 
0024 
00FF 
FFFF 
FF03 
533R if— 1 1 
R5D4 |S£| 
533R 


Examine 

1 

1R6C4 : FFFF FFFF 

i 

1R6C8 : FFFF FFFF 


1R6CC: 0000 0000 

1 

1R6D0 : 0000 0000 


0> 1R6D4 : 0000 533R 

H 

5> 1R6D8 : 0001 R6D4 


1R6DC : 0000 0018 

■ 

1R6E0 : 0000 0000 

m 

1R6E4 : 0000 0000 


1R6E8 : 0000 0BR0 

fe&f 


P 


- The PC window displays memory starting at the current value of the 
program counter (PC). The value of the PC is indicated by the 
"at" symbol (@) to the left of the first address displayed. 
Addresses at which breaks have been set are marked by asterisks 
(*). By default, memory in the PC window is displayed as 
disassembled instructions. In this example, a .Map file has been 
loaded to provide symbolic display of addresses. The program 
counter is set to START, and a break is set at START+2A. 

- The Registers window displays the values of the registers. 

Although not visible in this example, the previous value of a 
changed register is displayed in brackets ([]) to the right of the 
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current value. In the example, the D0 "cell" is selected to be 
changed. Cells are described below. 

- The upper Examine window displays the contents of the stack in 
long word format. The display of this window is "anchored" to A7 . 
This is indicated by the anchor symbol and the seven in the upper 
right of the window. The , 7> l to the left of the first address in 
this window shows that address register 7 points to this address. 

- The lower Examine window is not anchored to a specific register. 
The window happens to contain the addresses contained in A0 and 
A5 • 

- The Breakpoints window displays the addresses at which breakpoints 
are set. In the example, there is a breakpoint set at address 
START+2A. 


Features of MacDB Windows 


MacDB windows behave much like most Macintosh windows; however, they 
have a few unique features. 


Close Box 


=□= Enalmine 


m 


7> 19760: 

FFFF 

FFFF 

19764: 

0000 

oonc 

19768: 

0000 

0000 

1976C : 

0000 

FFFF 

19770: 

0000 

0000 

19774: 

0000 

4080 

19778: 

0000 

5F3C 

1977C : 

0000 

4080 

19780: 

0040 

975C 

19784: 

0001 

977E 

19788: 

0000 

0000 


0 


IS 

a 


Start Box 
Anchor Box 
Title Bar 
Align Box 
Scroll Arrow 


Scroll Bar 

Scroll Box 

Scroll Arrow 
Size Box 


The active window in a Macintosh application is the window with the 
highlighted title bar. As with other applications, there is only one 
active window at a time; however, unlike most others, it is not 
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necessary to select a window before selecting something within the 
window: A single click activates the window and performs an action. 
For example, if you click on a scroll arrow in an inactive window, the 
window becomes active and scrolls. 


The Close Box 


The close box is used to remove a window from the screen. The original 
PC, Registers, and Breakpoints windows cannot be closed. Duplicates of 
windows, made with the Duplicate command in the Window menu, can all be 
closed . 


The Title Bar 


The title bar is used to drag the window around on the screen. To 
change a window* s title, use the Title command in the Window menu. 


The Start Box 


The start box, the grey region below the title, is used to set the 
address of the first location displayed in the window. For example, if 
you click on the value shown for the PC in the Registers window and 
then click on the start box of an Examine window, the window is updated 
to display memory starting at the current value of the PC. The 
selecting of values within windows is discussed below in the section on 
cells . 


The Anchor Box 


The anchor box, to the right of the start box, displays the number of 
the register, if any, to which that window is anchored. For example, 
the upper Examine window is by default anchored to A7 , indicated by the 
anchor and the 7 in the anchor box. Whenever this window is updated, 
the address contained in A7 is the first address displayed. Note that 
the 7 could mean A7 or D7 • 

Anchors are set and cleared using the Anchor and No Anchor commands in 
the Window menu. They cannot be set for Register or Breakpoints 
windows • 


The Align Box 

It is not always possible for MacDB to determine whether memory data, 
such as disassembled instructions, should be aligned on word or long 
word boundaries. When you click the align box, just above the upper 
scroll arrow, the starting address of the window decreases by one word. 
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The Scroll Arrows 


The scroll arrows work in the usual manner. Clicking a scroll arrow 
causes the window to scroll one line in the indicated direction. 
Scrolling continues until the mouse button is released. 


The Scroll Bar 


Clicking the scroll bar, either above or below the scroll box, causes 
the next windowful of memory addresses to be displayed. Clicking 
repeatedly on the scroll bar is considerably faster than scrolling line 
by line, and you still see every address in the displayed range. 


The Scroll Box 


The scroll box works in the usual manner. Because there are many 
memory addresses, it is a very good tool for moving quickly through 
memory, but a fairly poor one for finding a specific address. 


The Size Box 


The size box works in the usual manner. It is used for increasing or 
decreasing the size of the window either horizontally or vertically. 


Values in Cells 


Most of the things that appear within windows are addresses or values. 
As such they are useful as input to various MacDB calls described 
below. All addresses and values can be selected by clicking on them. 
When a cell is selected, it is inverted on the screen. Only one cell 
can be selected at a time. 


Changing the Value in a Cell 

To change the value in a register or memory cell in the target machine, 
just select the value to be changed and then enter a new value or 
expression. A box appears to let you cancel or accept the new value. 

Expressions can contain hexadecimal values, the operators + - * /, and 
symbols that are currently defined (as explained below). Hexadecimal 
values must be preceded by $ if they might be confused with symbols. 

The operators * and / are of equal and higher precedence than the 
operators + and -, which are also of equal precedence. 

Most address cells can be selected, but not changed. The first address 
cell in a window can be changed. 
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Handy Hints 

You* 11 find while debugging that the disk drive does not stop spinning. 
If you execute an infinite loop, the system will realize that the disk 
isn't in use, and it will turn the drive off. Try entering and running 
the instruction $60FE (BRA *-2). Return control to MacDB by pressing 
the interrupt button on the programmer's switch. 

Another useful technique is to no-op out undesirable instructions. The 
opcode for a no-op is $4E71. 


MacDB Menus 


Debug Menu 


128K/512K Mac 

This message tells you the amount of RAM in the target (the other) 
machine . 


Heap Check On/Off 

Select this command if you wish the validity of the heap to be checked 
after each command executed by MacDB. If the command is selected, and 
errors are found in the heap, the range of addresses containing the 
fault is displayed in a box. 


Wait 


Wait instructs MacDB to wait for an interrupt from the target 
Macintosh. Execution of the target program does not resume if it was 
previously halted (see the Proceed command, below). 


Quit 

Quit leaves MacDB and restarts the Finder. 
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Run Menu 


Trace 


Trace causes MacDB to execute the instruction that is currently 
indicated by the PC. Once the instruction has completed, control 
returns to MacDB and all the windows are updated. 

System traps are treated as a single instruction. If you wish to trace 
the execution of a system trap, use the Trace Into ROM instruction, 
described below. 


Proceed 


Proceed causes execution of the program to resume where it was 
interrupted. This normally allows the program to continue as though it 
had not been interrupted. If the PC still points to the instruction 
that caused the exception, you must manually advance the PC. 

Normal execution cannot be resumed if the interrupt was caused by a Bus 
Error or an Address Error. 


Go Till 


Go Till places a temporary breakpoint at the indicated address. 
Execution continues until this breakpoint is encountered or some other 
exception occurs. At this point the temporary breakpoint is removed. 
You cannot place temporary breakpoints in ROM. 


Go To 


Go To causes execution to begin at the specified address. Control 
returns to MacDB when a breakpoint or some other exception occurs. 


Trace Into ROM 


The Trace Into ROM command is usually dimmed. When the PC indicates a 
system trap, Trace Into ROM is enabled. If you choose Trace Into ROM, 
MacDB dispatches the call and returns with the PC pointing to the first 
instruction in the ROM routine. You can then use the Trace command to 
execute the instructions in the ROM routine. 
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Bkpts Menu 

When you set a breakpoint, MacDB saves the instruction at the 
breakpoint address and replaces it with a TRAP #$ E instruction. When 
this address is executed, the exception caused by the TRAP instruction 
gives control to the Nub, which then calls MacDB. The instruction that 
was originally at that address is not executed. 

Because breakpoints are implemented by altering memory locations, they 
cannot be set in ROM. No warning is given if you try to set a 
breakpoint in ROM. 

The presence of a breakpoint is indicated in two ways: Its address is 
displayed in the Breakpoints window, and any occurrence of an address 
that contains a breakpoint, in any window, is marked by an asterisk. 

If the PC is at an address that contains a breakpoint, the PC symbol 
(@) is displayed instead. 


Set 

This command sets a breakpoint at the indicated address. The address 
is added to the Breakpoints window, and all references to that address 
in other windows are marked with an asterisk. 


Clear 


This command removes the breakpoint at the indicated address, if there 
is one. The address is removed from the Breakpoints window, and all 
references to that address in other windows are unmarked. 


Clear All 


This command clears all currently defined breakpoints. 


Window Menu 


New 

New creates a new Examine window and places it on the screen. It is 
useful if you want to look at several parts of memory at the same time. 


Duplicate 

This command makes a copy of the active window. All settings of the 
original window are duplicated. A duplicate window always has a close 
box. 
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This feature is particularly useful if you want to freeze a copy of a 
window for comparison with another (see Fro zen/ Thawed , below). 


Symbolic/Hex Address 

These two commands determine the format of the addresses displayed in 
the active window. Symbolic addresses can only be displayed if one or 
more .Map files have been opened (see the Open command in the Symbols 
menu). In this mode, addresses are displayed as offsets from the 
nearest defined label. 

When Hex Address is selected, all addresses are displayed in 
Hexadecimal. 

This command does not affect the symbolic display of system traps. 


Frozen/Thawed 


This command allows the active window to be "frozen" for future 
reference and comparison with unfrozen windows. A frozen window has a 
thick black line as its left border. 

Although a frozen window may be moved about on the screen, and the data 
in the target machine may change, the contents of its window will not 
change until it is thawed (or closed). 


Anchor/No Anchor 


The Anchor command lets you "anchor" the addresses displayed in a 
window to one of the registers. The first address displayed in an 
anchored window is the contents of the register to which it is 
anchored. The register to which a window is anchored is denoted by an 
anchor symbol followed by a register number in the window* s anchor box 
(see preceding figure). 

A window may be anchored to any register displayed in the Registers 
window with the exception of SR. 


Title 


This command allows you to change a window* s title. 
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Format Menu 


The Format menu allows you to select the format of the information 
displayed in the active window. You can select the format of each 
window except the Registers window. 


Inst 


This command causes the data in the active window to be displayed as 
machine-language instructions. Useful effective addresses are 
displayed to the right of the instructions. If a .Map file has been 
loaded, effective addresses are displayed symbolically. 

MacDB cannot always tell if instructions should be disassembled 
starting on a word or long word boundary. If you click on the align 
box, just above the upper scroll arrow, the starting address of the 
window is decreased by two. 


Char 


This command causes the data in the active window to be displayed as 
hexadecimal bytes. The ASCII character corresponding to each byte is 
displayed in brackets to the right of the value. If the value's ASCII 
character is not printable, a period is displayed. 


Word 


This command causes the data in the active window to be displayed as a 
sequence of hexadecimal words. To the right of each word is its ASCII 
representation. If a byte is not a printable ASCII character, a period 
is displayed. 


Lon e 

This command causes the data in the active window to be displayed as a 
sequence of long words. To the right of each long word is its ASCII 
representation. If a byte is not a printable ASCII character, a period 
is displayed. If the long word is the address of a defined symbol, the 
symbol is displayed to the right of the ASCII representation. 


Pascal String 

This command causes the data in the active window to be displayed as a 
sequence of Pascal strings (a length byte followed by a string). The 
first byte in the window is assumed to be a length byte. Subsequent 
characters are displayed until that many characters have been 
displayed, or until an invalid character is found. The next byte is 
then assumed to be a length byte. 
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List 


This command attempts to display the active window as a linked list. 

The first line in the window reads 

Offset = nnnn nnnn 

nnnn nnnn is the offset into the record where the link to the next 
record is found. To change the offset, just select the current offset 
value and type in a new value. 

The starting address of the window is the first byte of the first 
record. As many consecutive bytes of the record as will fit across the 
window are displayed. The offset is then added to the address of that 
line, and the contents of the calculated address is the starting 
address of the second record, which is displayed on the next line in 
the window. Records are displayed until the window is full, or until 
an invalid pointer is found. 

If all the records do not fit in the window, you can scroll downward to 
see subsequent records. You cannot scroll upward in the window. To 
move upward, you can reselect the starting address for the window. 


Search 


Search allows you to search memory for occurrences of a specified 
pattern within a specified range of memory addresses. When you choose 
the command, you are allowed to set the start address of the search, 
the end address of the search, a mask value, and a value. 

Each address in the memory range is logically ANDed with the mask and 
then compared with the specified value. If they match, then that 
address and its contents are displayed. 

If all the matching patterns do not fit within the window, you can 
scroll downward to see subsequent occurrences of the pattern. You 
cannot scroll upward in a Search window. To move upwards, you can 
enter a new start address, or you can select an address elsewhere on 
the screen, and then click in the start box, just below the window ! s 
title . 

You can use the mask to set the size of the pattern you are looking 
for. To search for a specific byte, set the mask to $FF. To search 
for a specific word, set the mask to $FFFF. To search for a long word, 
set the mask to $FFFFFFFF. 


A-Traps 

This command lets you monitor the execution of system traps in the 
target application. Four lines appear at the top of the window. These 
let you set the range of traps to be monitored, whether a break should 
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occur when a trap in the range is encountered, and whether the trap 
monitor feature is currently active. 

Trap numbers are in the range $A000 through $AFFF. Set first to 
indicate the lowest trap number to be monitored. Set last to indicate 
the highest trap number to be monitored. If first is equal to last, 
just that single trap is monitored. If you wish a break to occur when 
a trap in the specified range is encountered, set the Break option to 
True (by clicking on False). The setting of the auto-pop bit in the 
monitored traps is ignored. 

If you wish to temporarily disable the monitoring of traps, set Enable 
to False by clicking on True. 

Once all your settings are correct, choose Proceed in the Run menu. 

This allows the target program to execute, but all traps in the desired 
range are displayed within the window. If the Break option is set to 
true, then control returns to MacDB when each trap in the range is 
encountered (before it is executed). 

Note that you can have multiple windows each monitoring a different 
range of trap instructions. 

Clicking Debug interrupts the target machine at the next trap. 


MemBlock 


This display format allows you to examine memory blocks within a heap 
zone. When you choose this command, the starting address of the window 
is automatically set to the first memory block in the current heap zone 
(immediately following the zone header). 

Each line in the window displays an eight-byte memory block header, 
enclosed in square brackets, followed by as much of the memory block as 
will fit across the window. In the case of nonrelocatable blocks, the 
memory block immediately follows the header in memory. In the case of 
relocatable blocks, the second long word in the header is a pointer to 
the block's master pointer. Such pointers are preceded by asterisks. 

Subsequent lines in the window display the headers for subsequent 
memory blocks. You can scroll up and down through heap zones. 


Symbols Menu 

This menu is used to assign symbols to memory addresses and to clear 
such assignments. Symbols are stored in .Map files. 
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Value 


Value lets you discover a symbol’s value or a value’s symbol. Either 
select an address in memory or a symbol before choosing the command, or 
be prepared to enter an address or symbol after choosing this command. 
It will display the symbol and its value. 

If there is no .Map file loaded, or the specified address is outside of 
the program space, the value is displayed in hexadecimal. 


Open and Purge 

These commands let you control the display of symbols in MacDB. 

Each window (except Registers) can have a set of symbols assigned to 
it. When you first Open a .Map file, the symbols in the .Map file are 
assigned to all windows. These windows are treated as a group; opening 
a .Map file for any of them assigns new symbols to all of them. 

Purge clears the symbols assigned to the selected window and removes 
that window from the group. If you Open a .Map file with a purged 
window selected, the symbols are assigned to that window; it does not 
affect the symbols in other windows. 

MacDB is able to keep track of the symbols used by multiple segments, 
but they are bound to the segments that are in memory when the .Map 
file was opened. You must open the .Map file again if the loaded 
segmen t s change • 


About Symbols 


When you start up MacDB, only trap symbols are displayed. 

When you open a .Map file, the symbols in the .Map file are read into 
memory. Only symbols that were referenced using the XDEF directive are 
placed into a .Map file. 

If you want to use equates that are not addresses, you must use a trick 
to get them into a form that MacDB recognizes. Each entry in a .Sym 
file looks like this: 

LABEL $08 $xxxxxxxx 

and each entry in a .Map file looks like this: 

LABEL= s:xxxxxxxx 

in which s is the segment number, and xxxxxxxx is the value. Thus if 
you change all instances of the string ’ $08 $ * in a .Sym file to 
'= 0:’, and save it as a .Map file, the file can be opened and used by 
MacDB. 


Chapter 7 

The MacsBug Debuggers 
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About This Chapter 

This chapter describes the MacsBug family of debuggers. 

The first part of the chapter describes the various versions of MacsBug 
and how they work. The next part of the chapter describes the syntax 
of commands accepted by MacsBug. The end of the chapter describes the 
commands themselves. 


About MacsBug 

MacsBug is a line-oriented single-Macintosh debugger. It shares memory 
with the application being debugged, thus MacsBug may not fit in memory 
with very large applications. 

The features of MacsBug include 

- The ability to display and set memory and registers. 

- The ability to disassemble memory. 

- Stepping and tracing through both RAM and ROM. 

- Monitoring of system traps. 

- Display and checking of the system and application heaps. 

MacsBug gets control when certain 68000 exceptions occur. You can then 
examine memory, trace through the application, or set up break 
conditions and execute the application until those conditions occur. 


Setting Up MacsBug 

MacsBug is not selected like a normal application. If there is a file 
named MacsBug on the startup disk when the system is turned on or 
restarted, MacsBug is installed into the system, and the message 
"MacsBug installed" is displayed right below "Welcome to Macintosh". 

The startup application is then launched as usual. To use a particular 
version of MacsBug, place it on a startup disk and name it MacsBug. 

MacsBug is placed in memory just below the main screen buffer. The 
amount of memory required by MacsBug depends on the version in use. 

Five versions of MacsBug are included in the Macintosh 68000 
Development System. They are described below. 
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Macs Bug 

This version of MacsBug runs on a 128K Macintosh. When invoked, it 
saves part of the screen and provides ten lines of debugging display. 
When exited, it restores the screen. 

MacsBug uses about 18K of memory. It will not run under MacWorks . 


Max Bug 

This version of MacsBug should be used on 512K Macintoshes. When 
invoked, it saves almost the entire screen and provides a 40-line 
display. When exited, it restores the screen. This version of MacsBug 
displays trap names instead of trap numbers. 

MaxBug uses about 40K of memory. It will not run under MacWorks. 


TermBugA and TermBugB 


These versions of MacsBug send display information to an external 
terminal rather than to the Macintosh screen. TermBugA should be used 
if the terminal is connected to the modem port, and TermBugB should be 
used if the terminal is connected to the printer port. 

Communication over the serial ports is at 9600 baud, 8 data bits, 2 
stop bits, no parity bits, using the XOn/XOff protocol. 

TermBugA and TermBugB use about 12K of memory. They will not run under 
MacWorks . 


LisaBug 

LisaBug is functionally equivalent to MaxBug. You should use it when 
you are using a Lisa running MacWorks. LisaBug will not run on a 
Macintosh. 


Theory of Operation 

When installed, MacsBug puts pointers to itself in many of the hardware 
exception vectors in addresses $0000 through $00FF. It then remains 
dormant until one of "its” exceptions occurs. Here is the list of 
exceptions to which MacsBug responds: 

Exception number Assignment 

2 Bus Error 

3 Address Error 

4 Illegal Instruction 

5 Zero Divide 
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6 

CHK Instruction 




7 

TRAPV Instruction 




9 

Trace 




10 

Line 1010 Emulator 




11 

Line 1111 Emulator 




28 

Level 4 Interrupts 

(not 

with 

LisaBug) 

29 

Level 5 Interrupts 

(not 

with 

LisaBug) 

30 

Level 6 Interrupts 

(not 

with 

LisaBug) 

31 

Level 7 Interrupts 




47 

Trap $F Instruction 




68000 exception processing is described in the 68000 Reference Manual. 


Invoking Macs Bug 

The simplest way to generate an exception is to press the interrupt 
button (the rear button on the programmer's switch). When you are 
using LisaBug, press on the numeric keypad. 

Another way to generate an exception is to add a line such as 

DC .W $FF01 ; generate a line 1111 exception 

at the point in your program where you want MacsBug to first get 
control. (Actually any value $F000 through $FFFF can be used.) 

Another good technique is to place the system trap 

__De bugger ; invoke system trap $A9FF 

into your program at the point where you want MacsBug to get control. 
This trap is defined in the file ToolTraps .Txt (and MacTraps.D). 

In addition, you can invoke system trap $ABFF. This trap is designed 
for use with the Lisa Workshop development system; it's explained at 
the end of the chapter. 

When MacsBug gets control, it disassembles the instruction indicated by 
the PC and displays the contents of the registers. If the exception 
was caused by an $Fxxx, $A9FF, or $ABFF instruction, MacsBug displays 
the message 'USERBRK', advances the PC to the next instruction, and 
then disassembles the instruction and displays the registers. 

It then displays the greater-than symbol (>) as a prompt, indicating 
that it is ready to accept a command. 

MacsBug, MaxBug, and LisaBug replace part of the screen with the 
debugging display. To see the application screen while the debugger is 
active, press the tilde/opening quote key in the upper left of the 
keyboard. To restore the debugger* s display, press any character key. 
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Syntax of Macs Bug Commands 

Commands consist of one or two command characters followed by a list of 
zero or more parameters (depending on the command)* Parameters can be 
numbers, text literals, symbols, or simple expressions* 


Numbers 


Numbers can be entered in decimal or hexadecimal notation. Decimal 
numbers are preceded by an ampersand (&) and hexadecimal numbers are 
optionally preceded by a dollar sign ($). Numbers may be signed (+ or 
-); if they are, the sign should precede the notation symbol. Here are 
some numbers in several different formats. The formats shown are the 
same as those displayed by the Convert command (described below). 


Number 

Unsigned Hex 

Signed Hex 

Decim, 

$FF 

$000000FF 

$000000FF 

&255 

-$FF 

$FFFFFF01 

-$000000FF 

-&255 

&100 

$00000064 

$00000064 

& 1 00 

+10 

$00000010 

$00000010 

&16 


Text Literals 


A text literal is a one- to four-character ASCII string bracketed by 
single quotes (*). If a string is longer than four characters, only 
the first four characters are used. When used by MacsBug, text 
literals are right justified in a long word. Here are some examples: 

String Stored as 

'A' $00000041 

1 Fred * $46726564 

1 1234 1 $31323334 


Symbols 

Symbols are generally used to represent the registers. The symbols are 


RA0 through RA7 
RD0 through RD7 
PC 

TP 


Address registers A0 through A7 
Data registers D0 through D7 
Program counter 

Last address referenced ("Dot”) 
Current QuickDraw port (thePort) 
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Expressions 

Expressions are formed by operators acting on numbers, text literals, 
and symbols. The operators are 

+ addition (infix), assertion (prefix) 

subtraction (infix), negation (prefix) 

@ indirection (prefix) 

The indirection operator uses the long integer at the location pointed 
to by the operand. Here are some valid expressions: 

RA7+4 

1A700-010C 

TP+&24 

-RA0+RA1 - 1 FRED 1 +@@ 4C50 


Macs Bug Commands 

MacsBug commands can be divided into six groups: memory, register, 
control, A-Trap, heap zone, disassembly, and other miscellaneous 
commands • 

A Return character repeats the last command, unless specified otherwise 
in the descriptions below. 

Parameters are represented by descriptive words and abbreviations such 
as ’ADDRESS*, ’NUMBER 1 , and *EXPR*. All parameters can be entered as 
expressions • 


Memory Commands 


DM ADDRESS NUMBER (Display Memory) 

Displays NUMBER bytes of memory starting at ADDRESS. 

NUMBER is rounded up to the nearest 16 bytes. If NUMBER is omitted, 16 
bytes are displayed. If ADDRESS and NUMBER are omitted, the next 16 
bytes are displayed. 

Subsequent presses of the Return key display the next NUMBER bytes. 

The dot symbol is set to ADDRESS. 

If NUMBER is set to certain four character strings, memory is instead 
symbolically displayed as a data structure that begins at ADDRESS. The 
strings and the data structures they represent are 

*IOPB' Input/Output Parameter Block for File I/O 

’WIND' Window Record 
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* TERC 1 TextEdit Record 

Refer to Inside Macintosh for a description of these data structures. 

You can prematurely terminate a DM command by pressing the Backspace 
key. 


SM ADDRESS EXPR1 .. EXPRN (Set Memory) 

Places the specified values, EXPR1 through EXPRN, into memory starting 
at ADDRESS. The size of each value depends on the "width" of each 
expression. 

The width of a decimal or hexadecimal value is the smallest number of 
bytes that holds the specified value (four-byte maximum). Text 
literals are from one to four bytes long; extra characters are ignored. 
Indirect values are always four bytes long. The width of an expression 
is equal to the width of the widest of its operands. 

The dot symbol is set to ADDRESS. 


Register Commands 


Dn EXPR (Data Register) 

Displays or sets data register n. If EXPR is omitted, the register is 
displayed. Otherwise, the register is set to EXPR. 


An EXPR (Address Register) 

Displays or sets ADDRESS register n. If EXPR is omitted, the register 
is displayed. Otherwise, the register is set to EXPR. 


PC EXPR (Program Counter) 

Displays or sets the program counter. If EXPR is omitted, the program 
counter is displayed. Otherwise, the PC is set to EXPR. 

SR EXPR (Status Register) 

Displays or sets the status register. If EXPR is omitted, the status 
register is displayed. Otherwise the status register is set. 


TD 


(Total Display) 


Displays all registers 
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Control Commands 


BR ADDRESS COUNT (Break) 

Sets a breakpoint at ADDRESS. COUNT is the number of times that the 
breakpoint should be executed before breaking. If COUNT is omitted, 
the program is stopped the first time the breakpoint is hit. If 
ADDRESS is omitted, all breakpoints and current counts are displayed. 

A maximum of 8 different breakpoints can be set. 


CL ADDRESS (Clear) 

Clears the breakpoint at ADDRESS. If ADDRESS is omitted, all 
breakpoints are cleared. 


G ADDRESS (Go) 

Executes instructions starting at ADDRESS. If ADDRESS is omitted, 
execution begins at the address indicated by the program counter. 
Control does not return to MacsBug until an exception occurs. 

GT ADDRESS (Go Till) 

Sets a one-time breakpoint at ADDRESS, then executes instructions 
starting at ADDRESS. This breakpoint is automatically cleared after it 
is hit. 


T (Trace) 

Traces through one instruction. Traps are treated as single 
instructions • 


S NUMBER (Step) 

Steps through NUMBER instructions. If NUMBER is omitted, just one 
instruction is executed. Traps are not considered to be single 
instructions • 


SS ADDRESS 1 ADDRESS 2 (Step Spy) 

Calculates a checksum for the specified memory range, then does a Go. 
It then checks the checksum before each instruction is executed, and 
breaks into MacsBug if the checksum doesn't match. If ADDRESS1 and 
ADDRESS2 are omitted, this feature is turned off. 
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ST ADDRESS (Step Till) 

Steps through instructions until ADDRESS is encountered. Unlike Go 
Till, this command does not set a breakpoint. Thus it can be used to 
step through, and stop in, ROM. 


MR NUMBER (Magic Return) 

When debugging, you generally trace through a program one instruction 
at a time. MR lets you trace through to the end of a routine instead. 

When you use MR, it replaces the return address that is NUMBER bytes 
down in the stack with an address within MacsBug; then it does a Go 
(described above). The RTS that would have used that address returns 
to MacsBug instead of the caller. MacsBug restores the original return 
address, and then executes the RTS as if called by the Trace command. 
The prompt is then displayed, ready to trace the instruction after RTS. 

The usual way to use this routine is to trace until just after a JSR 
(return address 0 bytes down in the stack), and then do an MR (0 is the 
default NUMBER). The rest of the routine is executed, and control 
returns to MacsBug. 

This command isn’t repeated when you press Return; a Trace command is 
executed instead. 


RB (Reboot) 

Reboots the system. 


ES (Exit to Shell) 

Invokes the trap ExitToShell, which causes the startup application to 
be launched • 


A-Trap Commands 

The A-Trap commands are used to monitor "1010 emulator" traps. These 
commands use up to six parameters (TRAP1, TRAP 2 , ADDRESS 1 , ADDRESS2, 

D1 , and D2) that specify which traps and other conditions should be 
monitored. If no parameters are given, all traps are monitored. 

TRAP1 and TRAP2 specify the range of the traps. Operating System traps 
are in the range 0 through 255; Toolbox traps are between 255 and 511. 
If only TRAP1 is specified, the command is invoked for trap TRAP1 . If 
TRAP1 and TRAP2 are specified, the command is invoked for all traps in 
the range TRAP1 through TRAP2. ADDRESS1 and ADDRESS2 specify the range 
of calling addresses within which traps should be monitored. Finally, 
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Dl and D2 specify the values of data register 0 within which traps 
should be monitored. 

These commands set up conditions for the monitoring of traps. You 
generally use the Go command immediately after a trap command to await 
the use of a specified trap. When a trap in the indicated range is 
encountered appropriate information is displayed. Displayed trap 
numbers are given in full word format (Axxx) , 

Unlike break commands, only one A-Trap command is active at a time. 


AB TRAP1 TRAP 2 ADDRESS 1 ADDRESS 2 Dl D2 (A-Trap Break) 

Causes a break when the condition specified by the parameters is 
satisfied. 


AT TRAPl TRAP 2 ADDRESS 1 ADDRESS 2 Dl D2 (A-Trap Trace) 

Traces and displays each A-Trap, but doesn't break, when the condition 
specified by the parameters is satisfied. 

This command continues to display A-Traps until you press the interrupt 
button. 


AH TRAPl TRAP 2 ADDRESS 1 ADDRESS 2 Dl D2 (A-Trap Heap zone check) 

TRAPl must be greater than $2E. This command does an HC command just 
before executing each trap in the specified range. It displays the 
first two memory blocks that might contain errors. 


HS TRAPl TRAP 2 (Heap Scramble) 

Scrambles the heap zone, by moving relocatable blocks, when certain 
traps in the specified range are encountered. It always scrambles the 
heap zone as a result of NewPtr, NewHandle, and ReallocHandle calls. 

It scrambles the heap zone as a result of SetHandleSize and SetPtrSize 
if the new length is greater than the current length. 

This command is fastest if you set trapl to $18 and trap2 to $2D. 

The heap zone is not scrambled as a result of traps other than those 
named above. 

AS ADDRESS 1 ADDRESS 2 (A-Trap Spy) 

Calculates a checksum for the specified memory range, and then checks 
it before each trap. Breaks into MacsBug if the checksum doesn’t 
match. 
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AX (A- Trap Clear) 

Clears all A-Trap commands. 


Heap Zone Commands 

The heap zone commands act upon the current heap zone. When Macs Bug is 
started up, the current heap zone is the application heap zone. You 
can toggle the current heap zone between the application heap zone and 
the system heap zone using the HX command. 

Several commands cause MacsBug to scramble the heap zone. When MacsBug 
scrambles the heap zone, it rearranges all the relocatable blocks. 

This is useful for finding illegally used pointers to relocatable data 
structures • 


HX (Heap Exchange) 

Toggles the current heap zone between the system heap zone and the 
application heap zone. 


HC (Heap Check) 

Checks the consistency of the current heap zone. If an inconsistency 
is found, two blocks are displayed. The first appears correct, but 
might have a bad length; the second is definitely garbled. 


HD MASK (Heap Dump) 

MASK is optional. Whether or not MASK is used, it displays each block 
in the current heap zone in the following form: 

BlockAddr Type Size [Flags MP_location] [*] [RefNum ID Type] 

The blockAddr points to the start of the memory block. The type is F 
for a free block, P for a pointer, and H for a handle to a relocatable 
block. The size is the physical size of the block, including the 
contents, the header, and any unused bytes at the end of the block. 

For handles (type H) , Flags (the high nibble of the master pointer) and 
the master pointer location are given. Flags are: locked (bit 3), 
purgeable (bit 2), resource (bit 1), and unused (bit 0). The asterisk 
marks any immobile object (nonrelocatable blocks and locked relocatable 
blocks ) • 

For resource file blocks, three additional fields are displayed: the 
resource’s reference number, ID number, and type. 

If MASK is omitted, the dump is followed by a summary of the heap 
zone’s blocks. It begins with the six characters *HLP PF * , which 
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represent the six values that follow them. These values are 
H - number of relocatable blocks in the heap zone (handles) 

L - number of relocatable blocks that are Locked 
P - number of Purgeable blocks in the heap zone 
- SPACE, in bytes, occupied by purgeable blocks 
P - number of nonrelocatable blocks in the heap zone (pointers) 

F - total amount of Free space in the heap zone 
Here is a sample summary: 

HLP PF 0084 0004 0002 0000079E 0017 000003B4 


Note that block counts are single words, and values representing space 
in bytes are long word quantities. 


If MASK is used, the summary line displays the block counts of specific 
types of blocks. Possible values for MASK are: 


, H* 

» p » 

’F 1 

l R' 

1 xxxx 1 


Relocatable blocks (handles) 
Nonrelocatable blocks (pointers) 
Free blocks 
Resource blocks 

Resource blocks of type 'xxxx' 


If MASK is used, the heap summary takes this form: 


CNT ### <// of blocks of MASK type> <# bytes in those blocks> 


You can prematurely terminate an HD command by pressing the Backspace 
key. 


HP MASK (Heap Print) 

If you are using TermBugA or TermBugB, this command can be used to dump 
the heap zone to the other serial port. Communication is done at 9600 
baud, 8 data bits, 2 stop bits, and no parity bits, using the XOn/XOff 
protocol . 


HT MASK (Heap Total) 

Displays just the summary line from a heap zone dump. MASK works just 
as it does with the HD command. 
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Disassembler Commands 


ID ADDRESS (Instruction Disassemble) 

Disassembles one line at ADDRESS. If ADDRESS is omitted, the next 
logical location is disassembled. This sets the dot symbol to the 
ADDRESS. 

If it is Pascal code that was compiled with the {$D+} option on, and 
symbols have been turned on with the PX command, each address is 
automatically displayed as a routine name plus an offset. 


IL ADDRESS NUMBER (Instruction List) 

Disassembles NUMBER lines starting at ADDRESS. If NUMBER is omitted, a 
screenful of lines is disassembled. If both NUMBER and ADDRESS are 
omitted, a screenful of lines is disassembled starting at the next 
logical location. This command sets the dot symbol to the ADDRESS. 

If it is Pascal code that was compiled with the {$D+} option on, and 
symbols have been turned on with the PX command, each address is 
automatically displayed as a routine name plus an offset. 

You can prematurely terminate an IL command by pressing the Backspace 
key. 


PX (Symbol Toggle) 

Toggles whether or not symbols are displayed. By default, symbols are 
off. This affects the IL, ID, and WH commands. 


Miscellaneous Commands 


F ADDRESS COUNT DATA MASK (Find) 

Searches COUNT bytes from ADDRESS, looking for DATA after masking the 
target with MASK. As soon as a match is found, the ADDRESS and value 
are displayed, and the dot symbol is set to that ADDRESS. To search 
the next COUNT bytes, simply press Return. 

The size of the target (and default MASK) is determined by the width of 
DATA, and can only be 1, 2, or 4 bytes. Default MASK has all bits on. 


WH EXPR (Where) 

Displays the number, address, and with MaxBug, the name, of the trap 
specified by EXPR. 
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If EXPR is a name or is less than 512, it displays information for that 
trap. If EXPR is greater than or equal to 512, the trap whose code is 
closest to address EXPR is displayed. This is useful for finding out 
what trap was executing when an error occurred. 


CS ADDRESS1 ADDRESS2 (Checksum) 

Checksums the bytes in the range ADDRESS 1 through ADDRESS2 and saves 
that value. If ADDRESS2 is omitted, it checksums 16 bytes, starting at 
ADDRESS1. If ADDRESS 1 and ADDRESS2 are both omitted, it calculates the 
checksum for the last range specified, saves that value, and compares 
it to the previous checksum for that range. If the checksum hasn*t 
changed, it prints 'CHKSUM T 1 ; otherwise it prints T CHKSUM F f . 


CV EXPR (Convert) 

Displays EXPR as unsigned hexadecimal, signed hexadecimal, signed 
decimal, and text. 


RX (Register Exchange) 

Toggles the display mode so that the registers are or are not dumped 
during a trace command. The disassembly of the PC instruction is not 
affected . 


Handy Hints 


Stopping the Disk Drive 

When you are using the debugger, the disk drives don ! t stop spinning as 
they usually do. You can get a disk drive to stop by doing the 
following : 

1. Enter DM PC and remember the first word that is displayed. 

2. Enter SM PC 60FE, the instruction BRA *-2 , which is an infinite 
loop . 

3. Enter G and wait for the drive to stop spinning. 

4. When the drive stops spinning, press the interrupt button. 

5. Put the old word back into memory. 
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Using No-ops 

If you want to no-op out an instruction, replace the instruction with 
the number $4E71, the no-op opcode. 


Using MacsBug with the Lisa Workshop 

If you are using the Lisa Workshop development system, you can invoke 
MacsBug by declaring and calling the following procedure: 

PROCEDURE MacsBug; INLINE $A9FF; 

This procedure drops into MacsBug and displays the message 'USERBRK 1 . 

It then does a normal exception entry into MacsBug. 

If you want to display debugging information, declare and call this 
procedure : 

PROCEDURE Macs Bug Print (str: str255); INLINE $ABFF; 

When the $ABFF trap is encountered, MacsBug assumes that the top of the 
user’s stack has a pointer to a Pascal string. It prints out the 
string, displays the message USERBRK 1 , and does a normal exception 
entry into MacsBug. 

The Lisa Workshop Pascal compiler has an option that lets you 
symbolically display the names of routines and functions in MacsBug. 

If you compile your program using the {$D+} option, procedure names are 
automatically placed in the code at the end of each procedure or 
function. If you want to use the symbols, you should use PX to turn on 
symbolic display. 



Chapter 8 

The Resource Compiler 
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About This Chapter 

This chapter describes RMaker, an application that is used to produce 
resource files and to integrate resources into applications. 

The first part of this chapter describes RMaker. The next part of the 
chapter describes how to create an RMaker input file using predefined 
resource types and user-defined resource types. The final part of the 
chapter tells how to use RMaker to create a new resource file from the 
input file. 


About RMaker 


RMaker is the Macintosh 68000 Development System* s Resource Compiler. 

It is very similar to the RMaker program in the Lisa Workshop, but some 
changes have been made to the syntax. Be careful if you are converting 
resource files from one system to the other. 

RMaker takes a text file as input and produces a resource file. The 
text file contains an entry for each resource, as described below. 

These entries can specify all information necessary to define the 
resources, or they can cause existing resources to be read from other 
files . 

For example, during program development, you* 11 typically use separate 
application and resource files. Once the application is finished, you 
should combine these files. Simply use the INCLUDE statement to read 
in the application created by the Linker. It is already stored as 
resources of type *CODE*. 


RMaker Input Files 

An RMaker input file is a text file that may be created using the 
Editor. By convention, RMaker input files have the extension .R. 

RMaker ignores all comment lines and blank lines (except in some cases 
a blank line may be required). It also ignores leading and embedded 
spaces (except in lines defined to be strings). Comment lines begin 
with an asterisk. To put comments at the end of other RMaker lines, 
precede the comment with two consecutive semicolons (;;). 


Naming the Resource File 

The first nonblank and noncomment line of the input file specifies the 
name of the resource file to be created. If the filename has the 
extension .Rel, a file is generated that can be linked using the Linker 
(see the section on resources in Chapter 4). If the file is to be an 
application, it should have no extension. If not, the file will be a 
resource file and should have the extension .Rsrc. The line following 
the resource’s filename should either specify the file type and creator 
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bytes for the Finder or be blank. For example, the two lines 

NewResFile .Rsrc 
PNTGMPNT 

specify the file named NewResFile .Rsrc as the output file, and the 
bytes 1 PNTGMPNT 1 as the type and creator bytes. These bytes tell the 
Finder that the file is a painting file, created by MacPaint. (The 
Finder will try to launch MacPaint if you select and open this file!) 

More typically, these two lines will look like this: 

My Application 
APPLMYAP 

This designates the file My Application as the output file. The file is 
an application (type f APPL f ) of type , MYAP'. 

If you do not specify a value for these bytes, they are set to 0. 


Appending to an Existing Resource File 

If you wish to add the resources defined in your input file to those in 
an existing resource file, simply precede the filename with an 
exclamation point. For example 

!01dResFile .Rsrc 

tells RMaker to add the new resources to the file OldResFile .Rsrc . 


Adding Resources 

The rest of the resource file consists of INCLUDE statements and "Type 
statements". 

INCLUDE statements are used to read in entire resource files. An 
INCLUDE statement looks like this: 

INCLUDE filename 

Type statements consist of the word "Type" followed by the resource 
type and, below that, one or more resource definitions. The resource 
type must be capitalized to match a predefined resource type. 

The following statement creates three resources of type ? STR '. 
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TYPE STR 

,1 

This is a string 

.2 

Gnirts a si siht 
,3 

Hits is a grints 

It is not necessary for all resources of a given type to be declared 
together; however, all resources of a type must have unique resource 
IDs. If you specify a resource ID that is already in use, the new 
resource replaces the old one. 

A resource looks like this : 

[resource name] , resource ID [(resource attribute byte)] 
type-specific data 

The square brackets indicate that the resource name and resource 
attribute byte are optional. Don't place these brackets in your input 
file. The comma before the resource ID is mandatory. The default 
attribute byte is 0. Here are some sample resource definitions: 

TYPE STR 
NewStr ,4 (32) 

This resource has a name and an attribute byte!! 

,5 

This one has only a resource ID. 

My NewStr ,6 

This has a name and a resource ID. 

The type-specific data is different for each resource type. As you 
have probably guessed, the type-specific data for a 1 STR ' resource is 
simply a string. The next section describes the type-specific data for 
the resource types defined by RMaker. 


Defined Resource Types 

RMaker has 12 defined resource types: 1 ALRT 1 , ' BNDL ' , ' CNTL' , 1 DITL* , 

1 DLOG 1 , ' FREF 1 , 1 GNRL 1 , * MENU T , 'PROC', * STR f , 1 STR# 1 , and 'WIND*. 

The format of the type-specific data for each type is shown by example, 
below. The type 'GNRL' is used to define your own resource types. It 
is explained later. 


Syntax of RMaker Lines 

There are just a few general rules that apply to lines read by RMaker. 

- Leading and embedded blanks are ignored, except when necessary to 
separate multiple numbers on a line, or when they are part of a 
string . 
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- Numbers are decimal, unless specified otherwise. 

- RMaker is sensitive to line breaks. Thus if a type description, 
below, shows four values on a single line, you must put four 
values on a single line. 

Two special symbols can be used in resource definitions: the 
continuation symbol (++) and the enter ASCII symbol (\). 

++ goes at the end of a line that is continued on the next line. 

\ precedes two hexadecimal digits. That ASCII character is 

entered into the resource definition. 

Look at the description of the * STR * type for examples of these 
special symbols. As previously mentioned, blank lines are ignored. To 
enter a blank line that isn’t ignored, use \20. 

You will notice that some of the resources are listed as templates, 
while others are not. A template is a list of parameters used to build 
a Toolbox object; it is not the object itself. 


ALRT 

Alert Template 




TYPE ALRT 






,128 


; resource ID 




50 50 250 250 


; top left bottom right 




1 


; resource ID of item list 




7FFF 


; stages word in hexadecimal 




BNDL 

Application Bundle 




TYPE BNDL 






,128 


; resource ID 




MPNT 0 

. 

; bundle owner 




ICN# 


; resource type 




0 128 1 129 


; local ID 0 maps to resource 

ID 

128; 1 

to 129 

FREF 


; resource type 




0 128 1 129 


; local ID 0 maps to resource 

ID 

128; 1 

to 129 

Note: the number of mappings from local ID to resource ID 

is variable. 

Simply include multiple mappings on a single line. 




CNTL 

Control Template 




TYPE CNTL 






,130 


; resource ID 




Stop 


; title 




244 40 260 80 


top left bottom right 




Invisible 

: 

; see note 




0 


,; ProcID (control definition 

ID) 
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0 ;; RefCon (reference value) 

010 ; ; minimum maximum value 

Note: Controls can be defined to be Visible or Invisible. Only the 
first character (V or I) is significant. 


DITL Dialog or Alert Item List 


TYPE DITL 
,129 


5 


; ; resource ID 
; ; 5 items in list 


staticText 
20 20 32 100 
Whoopie 


; static text dialog item (see note) 
; top left bottom right 
; message 


editText 
20 120 32 200 
Default message 


; editable text dialog item (see note) 
; top left bottom right 
; message 


radioButton 
40 40 60 150 
Hello 


; radio button dialog item (see note) 
; top left bottom right 
; message 


checkBox Disabled 
75 40 95 150 
Good Bye 


; disabled dialog item (see note) 
; top left bottom right 
; message 


button 

75 160 95 200 
Hi! 


; button dialog item (see note) 
; top left bottom right 
; message 


Note: Five types of dialog items are defined: Static text, Editable 
text. Radio Buttons, Check Boxes, and Buttons. These items are assumed 
to be enabled. Otherwise you may specify Disabled. Only the first 
character of an item definition word is significant (S,E,R,C,B,D) . 


DLOG Dialog Template 

TYPE DLOG 

,3 ;; resource ID 

This is a dialog box. ;; message 

100 100 190 250 ; ; top left bottom right 

Visible GoAway ;; box status (see note) 

0 ;; procID (dialog definition ID) 

0 ;; refCon (reference value) 

129 ;; ID of item list ('DITL 1 , above) 

Note: A dialog box can be Visible or Invisible. GoAway and NoGoAway 

determine whether or not the dialog box has a close box. Only the 
first characters (V,I,G,N) are significant. 
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FREF File Reference 

TYPE FREF 

,128 ;; resource ID 

APPL 0 ;; file type, local ID of icon 

,129 ;; resource ID 

TEST 127 myFile ;; file type, local ID of icon, filename 

Note: If there is no filename, it can be omitted. 


MENU Menu 

TYPE MENU 

resource ID 
menu title 
item 1 
item 2 
item 3 

item 4 (draw a line) 
item 5 

MUST be followed by a blank line ! ! 


Transfer 

Edit 

Asm 

Link 

(“ 

Exec 


PROC Procedure 

TYPE PROC 

,128 ;; resource ID 

MyProcedure ;; filename 

This type is used to create resources that contain code. It reads the 
first code segment from an application file (the 'CODE 1 resource with 
ID = 1), strips the first four bytes off of it (used by the Segment 
Loader), and saves it as a resource of type 'PROC*. It is useful for 
defining code types such as 'DRVR', 'WDEF', and 'PACK'. An example is 
given below in the section on creating your own resource types. 


STR String 

TYPE STR 

,1 

This is a string 
,23 

This is a string ++ 
that shows the line ++ 
continuation characters 


;; 'STR ' (space required) 
; ; resource ID 
; ; and a string 

; ; resource ID 
; ; and a long string 


,25 (32) 

I've got attributes! 


;; resource ID, optional attribute byte 
; ; and a string 
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,27 ;; resource ID 

Testing, \31 , \32, \33 ;; 'Testing, 1, 2, 3' the hard way 


A Number of Strings 


STR/ / 

TYPE STR// 

,1 

4 

This is string one 
And string two 
Third string 
Bench warmer 


; ; resource ID 
; ; number of strings 
;; and the strings..* 


WIND Window Template 


TYPE WIND 
,128 

Wonder Window 
40 80 120 300 
Invisible Go Away 
0 
0 


; title 

; top left bottom right 
; window status (see note) 

; ProcID (window definition ID) 
; Ref Con (reference value) 


Note: A Window can be Visible or Invisible; GoAway and NoGoAway 
determine whether or not the window has a close box. Only the first 
character of each option (V,I,G,N) is significant. 


Creating Your Own Types 

There are two ways to create your own resource types. The first is to 
equate a new type to an existing type. For example, you can create a 
resource of type 'DRVR' like this: 

TYPE DRVR = PROC ;; type 1 DRVR 1 is just like 'PROC 1 

,17 (32) ;; resource ID, attribute byte 

My Driver ; ; filename 

The file MyDriver should be a single-segment application, as created by 
the Linker. Recall that the 'PROC' type reads in the resource of type 
'CODE* with ID = 1 ; then it strips off the header bytes. 

The other way to create your own type is to equate the new type to 
'GNRL' and then to specify the precise format of the resource. A set 
of element type designators lets you define the type of each element 
that is to be placed in the resource. 

Here are the element type designators : 

•P Pascal string 

•S String without length byte 
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.1 Decimal integer 

•L Decimal long integer 

.H Hexadecimal 

.R Read resource from file, .R is followed by: 

filename type ID 

For example, to define a resource of type ’CHRG* consisting of the 
integer 57 followed by the Pascal string ’Finance charges’, you could 
use the following type assignment: 


TYPE CHRG = GNRL 



Finance charges 


;; define type ’CHRG* 
; ; resource ID 
; ; a decimal integer 

; ; a Pascal string 


A more practical example: An application that has its own icon must 
define an icon list and reference it using ’FREF* (described above). 
Such an icon list can be defined as follows: 


TYPE ICN# = GNRL 
,128 

.H 

0001 0002 0003 0004 


; icon list for an application 
; resource ID 

; enter 2 icons in hexadecimal 
; each is 32 bits by 32 bits 


007D 007E 007F 0080 


;; for 128 words total 


The .R type designator is used to include an existing resource as part 
of a new resource type. For example, to read an existing ’FONT 1 
resource into a new resource of type ’FONT* , use the following resource 
definition : 


TYPE FONT = GNRL 
,268 

.R 

System FONT 268 


; define a new type 
; resource ID 

; read from the System file 
; the ’FONT’ resource with ID=268 


Using RMaker 

Once you have created the input file to RMaker, the hard work is done. 
Simply select and open the application RMaker. The standard file 
selection window is automatically opened. Select the file you want to 
compile, and off it goes. 

By default, the standard file selection window displays all the text 
files on the disk. If you want to display only the .R files, Cancel 
the selection window, choose .R Filter from the File menu, then choose 
Compile from the File menu to redisplay the file selection window. 
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File Transfer 


Resource Compiler 


Output File MDS2:Window.Rsrc 


Source File Window.R 


Stat icText 
15 20 36 300 

This sample program was written 


Data Size: 
Map Size: 
Total Size 


Stat i cText 
35 20 56 300 

just to prove it could be done! 


♦WIND Resource # 1 spec i f i es th< 
* for the window in which editir 
♦call to GetNewWindow. 


Type WIND 
, 1 

fl Samp I e 
50 40 300 450 
Uisible NoGoRway 


When RMaker is compiling a file, the name of the source file is 
displayed in the upper left of the window, and the name of the output 
file is displayed in the upper right. As the file is compiled, the 
current size of the resource data, the size of the resource map, and 
the total size are tracked on the right half of the screen. In 
addition, as each line is compiled, it is displayed on the screen. 

If there are no errors in the RMaker input file, a resource file with 
the specified name is created. 


Errors in the Input File 

If an error occurs, the line containing the error is the last line on 
the screen. RMaker then displays a box with an error message in it. 

RMaker errors are listed in an appendix. 


z 

□ 



Appendix A 


Sample Program Listing 



□ 
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The Window Sample Program 


File Window. Asm 

Macintosh 68000 Development System — Programming Example 


; This application displays a window within which you can enter and edit 
; text. Program control is through three menus: the Apple menu, the File 
; menu, and the Edit menu. 

; The Apple menu has the standard desk accessories and an About feature. 

; The File menu lets you quit the application. 

; The Edit menu lets you cut, copy, paste, and clear the text in the window 

; or in the desk accessories. Undo is provided for desk accesories only. 

; Command key equivalents for undo, cut, copy, and paste are provided. 

; Cutting and pasting between the application and the desk accessories is 
; not supported. This requires use of the Scrap Manager. 

; This program requires the use of a resource file called "Window. Rsrc" 

; Window. Rsrc is created from "Window. R" using RMaker 

INCLUDES 

Include MacTraps.D ; Use System and ToolBox traps 

Include ToolEqu.D ; Use ToolBox equates 

; Use of Registers 

; Operating System and Toolbox calls always preserve D3-D7, and A2-A4. 

; Register use: A5-A7 are reserved by the system 
; D1-D3 , A0-A1 are unused 

; DO is used as a temp 

ModifyReg EQU D4 ; D4 holds modifier bits from GetNextEvent 

MenuReg EQU D5 ; D5 holds menu ID from MenuSelect , MenuKey 

MenuItemReg EQU D6 ; D6 holds item ID from MenuSelect , MenuKey 

AppleHReg EQU D7 ; D7 holds the handle to the Apple Menu 

TextHReg EQU A2 ; A2 is a handle to the TextEdit record 

WindowPReg EQU A3 ; A3 is a pointer to the editing window 

EditHReg EQU A4 ; A4 is a handle to the Edit menu 

EQUATES 

; These are equates associated with the resources 
; for the Window example . 

AppleMenu EQU 1 ; First item in MENU resource 

Aboutltem EQU 1 ; First item in Apple menu 

FileMenu EQU 2 ; Second item in MENU resource 

Quit Item EQU 1 ; First item in File menu 

EditMenu EQU 3 ; Third item in MENU resource 

Undo Item EQU 1 ; Items in Edit menu 

Cutltem EQU 3 ; (Item 2 is a line) 

Copy Item EQU 4 

Pasteltem EQU 5 

Clearltem EQU 6 

AboutDialog EQU 1 ; About dialog is DLOG resource #1 

Buttonltem EQU 1 ; First item in DITL used by DLOG #1 

ASample EQU 1 ; Sample Window is WIND resource #1 

; These are modifier bits returned by the GetNextEvent call. 

activeBit EQU 0 ; Bit position of de/activate in Modify 

cmdKey EQU 8 ; Bit position of command key in Modify 

shiftKey EQU 9 ; Bit position of shift key in Modify 
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. XDEFs 

; XDEF all labels that are to be symbolically displayed by debugger. 


XDEF 

Start 

XDEF 

InitManagers 

XDEF 

OpenResFile 

XDEF 

SetupMenu 

XDEF 

SetupWindow 

XDEF 

SetupTextEdit 

XDEF 

Activate 

XDEF 

Deactivate 

XDEF 

Update 

XDEF 

KeyDown 

XDEF 

MouseDown 

XDEF 

SystemEvent 

XDEF 

Content 

XDEF 

Drag 

XDEF 

InMenu 

XDEF 

About 


; Main Program 

Start 


BSR 

BSR 

BSR 

BSR 

BSR 


InitManagers 

OpenResFile 

SetupMenu 

SetupWindow 

SetupTextEdit 


Initialize managers 
Open the resource file 
Build menus, draw menu bar 
Draw Editing Window 
Initialize TextEdit 


EventLoop 


; MAIN PROGRAM LOOP 


SystemTask ; 

7 PROCEDURE TEIdle (hTE : TEHandle) ; 
MOVE . L TextHReg , - (SP ) 

TEIdle 


Update Desk Accessories 

Get handle to text record 
blink cursor etc. 


FUNCTION 


GetNextEvent (eventMask : INTEGER; 

VAR theEvent : EventRecord) : BOOLEAN 


CLR 

-(SP) 

; Clear space for result 

MOVE 

#$0FFF,- (SP) 

; Allow 12 low events 

PEA 

EventRecord 

; Place to return results 

GetNextEvent 

; Look for an event 

MOVE 

(SP) +, DO 

; Get result code 

BEQ 

EventLoop 

; No event . . . Keep waiting 

BSR 

HandleEvent 

; Go handle event 

BEQ 

RTS 

EventLoop 

; Not Quit, keep going 
; Quit, exit to Finder 


; Note: When an event handler finishes, it returns the Z flag set. If 
; Quit was selected, it returns with the Z flag clear. An RTS is 

; guaranteed to close all files and launch the Finder. 

. InitManagers 

InitManagers 


PEA 

-4 (A5) 

; Quickdraw' s global area 

_InitGraf 


; In it Quickdraw 

InitFonts 


; Init Font Manager 

MOVE . L 
FlushEvents 

#$0000FFFF, DO 

; Flush all events 

InitWindows 


; Init Window Manager 

InitMenus 


; Init Menu Manager 

CLR.L - (SP) 


; No restart procedure 

InitDialogs 


; Init Dialog Manager 

TEInit 


; Init Text Edit 

InitCursor 

RTS 


; Turn on arrow cursor 
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OpenResFile 


OpenResFile 

; For development, we are keeping the resources in a separate file. The 
; application can be sped up by adding the resources to the application' s 
; file, which makes the OpenResFile call unneccessary . Note: normally the 
; explicit mention of MDS2 is considered bad style; the resource file 
; should be on the same volume as the program. However, it must be done 
; like this or Transfer looks on the wrong volume. 

; FUNCTION OpenResFile (fileName: str255) : INTEGER; 

CLR -(SP) ; Space for refNum 

PEA 'MDS2 : Window .Rsrc' ; Name of resource file 

OpenResFile ; Open it 

HOVE (SP)+,D0 ; Discard refNum 

RTS 


SetupMenu 


SetupMenu 

; The names of all the menus and the commands in the menus are stored in the 
; resource file. The way you build a menu for an application is by reading 
; each menu in from the resource file and then inserting it into the current 
; menu bar. Desk accessories are read from the system resource file and 
; added to the Apple menu . 

; Apple Menu Set Up. 


; FUNCTION 
CLR.L 
MOVE 
GetRMenu 
HOVE . L 
MOVE . L 


GetMenu (menu ID: INTEGER): MenuHandle; 

-(SP) ; Space for menu handle 

#AppleMenu, - (SP) ; Apple menu resource ID 

; Get menu handle 

(SP) ,AppleHReg ; Save for lat^r comparison 

(SP),-(SP) ; Copy handle for AddResMenu 


; PROCEDURE 
CLR 

InsertMenu 


InsertMenu (menu : MenuHandle; beforelD: INTEGER); 
-(SP) ; Append to menu 

; Which is currently empty 


; Add Desk Accessories Into Apple menu (Apple menu handle already on stack) 


; PROCEDURE 
MOVE . L 
AddResMenu 


AddResMenu (menu: MenuHandle; theType: ResType) ; 
#' DRVR' , - (SP) ; Load all drivers 

; And add to Apple menu 


; File Menu Set Up 


; FUNCTION 

CLR.L 

MOVE 

GetRMenu 


GetMenu (menu ID : INTEGER) : MenuHandle; 

-(SP) ; Space for menu handle 

#FileMenu, - (SP) ; File Menu Resource ID 

; Get File menu handle 


; PROCEDURE 
CLR 

InsertMenu 


InsertMenu (menu : MenuHandle; beforelD: INTEGER); 
-(SP) ; Append to list 

; After Apple menu 


; Edit Menu Set Up 


; FUNCTION 

CLR.L 

MOVE 

GetRMenu 
HOVE . L 

; PROCEDURE 
CLR 

_InsertMenu 

DrawMenuBar 

RTS 


GetMenu (menu ID: INTEGER) : MenuHandle; 

-(SP) ; Space for menu handle 

#EditMenu, - (SP) ; Edit menu resource ID 

; Get handle to menu 
(SP) ,EditHReg ; Save for later 

; Leave on stack for Insert 
InsertMenu (menu : MenuHandle; beforelD: INTEGER); 
-(SP) ; Append to list 

; After File menu 
; Display the menu bar 
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SetupWindow 


SetupWindow 


; The window parameters are stored in our resource file. Read them from 
; the file and draw the window, then set the port to that window. Note that 
; the window parameters could just as easily have been set using the call 
; NewWindow, which doesn't use the resource file. 


; FUNCTION GetNewWindow (windowID: INTEGER; wStorage: Ptr; 

; behind: WindowPtr) : WindowPtr; 

CLR.L -(SP) ; Space for window pointer 

MOVE tASample, - (SP) ; Resource ID for window 

PEA WindowStorage (A5) ; Storage for window 

MOVE . L #-l, - (SP) ; Make it the top window 


GetNewWindow 
MOVE . L (SP) , WindowPReg 


Draw the window 
Save for later 


; PROCEDURE 
SetPort 
RTS 


SetPort (gp: Graf Port) ; 


Pointer still on stack 
Make it the current port 


SetupTextEdit 


SetupTextEdit 


; Create a new text record for TextEdit, and define the window within which 
; it will be displayed. Note that if the window boundaries are changed in 
; the resource file, DestRect and ViewRect will have to be changed too. 


; PROCEDURE 
CLR.L 
PEA 
PEA 
TENew 
MOVE . L 
RTS 


TENew (destRect, viewRect : Rect) : TEHandle; 
-(SP) ; Space for text handle 

DestRect ; DestRect Rectangle 

ViewRect ; ViewRect Rectangle 

; New Text Record 

(SP) +, TextHReg ; Save text handle 


Event Handling Routines 


HandleEvent 


; Use the event number as an index into the Event table. These 12 events 
; are all the things that could spontaneously happen while the program is 
; in the main loop. 


MOVE 

Modify , Modi fyReg 

MOVE 

What , DO 

ADD 

DO, DO 

MOVE 

EventTable (DO) , DO 

JMP 

EventTable (DO) 


; More useful in a reg 
; Get event number 
; *2 for table index 
; Point to routine offset 
; and jump to it 


EventTable 


DC. W 
DC. W 
DC. W 
DC. W 
DC. W 
DC. W 
DC. W 
DC. W 
DC. W 
DC. W 
DC. W 
DC. W 


NextEvent-EventTable 

MouseDown-EventTable 

NextEvent-EventTable 

KeyDown-EventTable 

NextEvent-EventTable 

KeyDown-EventTable 

Update-Event Table 

NextEvent-EventTable 

Act ivate-Event Table 

NextEvent-EventTable 

NextEvent-EventTable 

NextEvent-EventTable 


Null Event (Not used) 
Mouse Down 
Mouse Up (Not used) 
Key Down 

Key Up (Not used) 

Auto Key 
Update 

Disk (Not used) 
Activate 
Abort (Not used) 
Network (Not used) 

I/O Driver (Not used) 
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Event Actions 


Activate 


; An activate event is posted by the system when a window needs to be 
; activated or deactivated. The information that indicates which window 
; needs to be updated was returned by the NextEvent call. 


CMP.L 

BNE 

BTST 

BEQ 


Message, WindowPReg 
NextEvent 

#ActiveBit , Modif yReg 
Deactivate 


; Was it our window? 

; No , get next event 
; Activate? 

; No, go do Deactivate 


; To activate our window, activate TextEdit, and disable Undo since we don't 
; support it. Then set our window as the port since an accessory may have 
; changed it. This activate event was generated by SelectWindow as a result 
; of a click in the content region of our window. If the window had scroll 
; bars, we would do ShowControl and HideControl here too. 


; PROCEDURE TEActivate (hTE: TEHandle); 

MOVE.L TextHReg, - (SP) ; Move Text Handle To Stack 

TEActivate ; Activate Text 


; PROCEDURE Disableltem (menu :MenuHandle; item: INTEGER) ; 
MOVE.L EditHReg, - (SP) ; Get handle to the menu 

MOVE #UndoItem, - (SP) ; Enable 1st item (undo) 

Disableltem 


SetOurPort 


used by InAppleMenu 


; PROCEDURE 
MOVE . L 
SetPort 


SetPort (gp: GraphPort) ; Set the port to us, since 
WindowPReg, - (SP) ; an accessory might have 

; changed it . 


NextEvent 


MOVEQ #0, DO 
RTS 


Say that it's not Quit 
return to EventLoop 


Deactivate 


; To deactivate our window, turn off TextEdit, and Enable undo for the desk 
; accessories (which must be active instead of us) . 


; PROCEDURE TEDeActivate (hTE: TEHandle) 

MOVE.L TextHReg, -(SP) ; Get Text Handle 

TeDeActivate ; Un Activate Text 


; PROCEDURE Enableltem (menu : MenuHandle; item: INTEGER) ; 
MOVE.L EditHReg,- (SP) ; Get handle to the menu 

MOVE #UndoItem, - (SP) ; Enable 1st item (undo) 

Enableltem 

BRA NextEvent ; Go get next event 


Update 

; The window needs to be redrawn. Erase the window and then call TextEdit 
; to redraw it . 

; PROCEDURE BeginUpdate (theWindow: WindowPtr) ; 

MOVE.L WindowPReg, - (SP) ; Get pointer to window 

_BeginUpDate ; Begin the update 

; EraseRect (rUpdate: Rect) ; 

PEA ViewRect 

EraseRect 


; Erase visible area 
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; TEUpdate (rUpdate: Rect; hTE: 

PEA ViewRect 

MOVE . L TextHReg, - (SP) 

_TE Update 


TEHandle) ; 

; Get visible area 
; and handle to text 
; then update the window 


; PROCEDURE 
MOVE . L 
EndUpdate 
BRA 


EndUpdate (theWindow: WindowPtr) ; 

WindowPReg, - (SP) ; Get pointer to window 

; and end the update 

NextEvent ; Go get next event 


KeyDown 

; A key was pressed. First check to see if it was a command key. If so, 
; go do it. Otherwise pass the key to TextEdit. 


BTST 

BNE 


#CmdKey, ModifyReg ; Is command key down? 

CommandDown ; If so, handle command key 


; PROCEDURE 
MOVE 
MOVE . L 
TEKey 
BRA 


TEKey (key: CHAR; hTE 
Message+2, - (SP) 
TextHReg, -(SP) 

NextEvent 


TEHandle) ; 

Get character 
and text record 
Give char to TextEdit 
Go get next event 


CommandDown 


; The command key was down. Call MenuKey to find out if it was the command 
; key equivalent for a menu command, pass the menu and item numbers to Choices. 


; FUNCTION 
CLR.L 
MOVE 
MenuKey 

Move 

MOVE 

BRA 


MenuKey (ch:CHAR): Longlnt; 

-(SP) ; Space for Menu and Item 

Message+2, - (SP) ; Get character 

; See if it's a command 
(SP) +, MenuReg ; Save Menu 

(SP) +, MenuItemReg ; and Menu Item 

Choices ; Go dispatch command 


-Mouse Down Events And Their Actions 


MouseDown 


; If the mouse button was pressed, we must determine where the click 
; occurred before we can do anything. Call FindWindow to determine 
; where the click was; dispatch the event according to the result. 


; FUNCTION 
CLR 

MOVE . L 
PEA 

FindWindow 

MOVE 

ADD 

MOVE 

JMP 


FindWindow (thePt: Point; 

VAR whichWindow: WindowPtr) : INTEGER; 


“(SP) 

Point, -(SP) 

WWindow 

(SP) +, DO 
DO, DO 

WindowTable (DO) , DO 
WindowTable (DO) 


Space for result 

Get mouse coordinates 

Event Window 

Who' s got the click? 

Get region number 
*2 for index into table 
Point to routine offset 
Jump to routine 


WindowTable 


DC. W 
DC. W 
DC. W 
DC. W 
DC. W 
DC. W 
DC. W 


NextEvent-WindowTable ; 
InMenu-WindowTable ; 
SystemEvent-WindowTable 
Content-WindowTable ; 
Drag-WindowTable ; 
NextEvent-WindowTable ; 
NextEvent-WindowTable ; 


In Desk (Not used) 

In Menu Bar 
; System Window 
In Content 
In Drag 

In Grow (Not used) 

In Go Away (Not used) 
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SystemEvent 


; The mouse button was pressed in a system window. SystemClick calls the 
; appropriate desk accessory to handle the event. 


; PROCEDURE 
PEA 

MOVE . L 
SystemClick 
BRA 


SystemClick (theEvent: EventRecord; 

theWindow: WindowPtr); 

EventRecord 
WWindow, - (SP) 


NextEvent 


Get event record 
and window pointer 
Let the system do it 
Go get next event 


Content 


; The click was in the content area of a window. If our window was in 
; front, then call Quickdraw to get local coordinates, then pass the 
; coordinates to TextEdit. We also determine whether the shift key was 
; pressed so TextEdit can do shift-clicking. If our window wasn't in 
; front, move it to the front, but don't process click. 


CLR.L -(SP) 

FrontWindow 
MOVE . L (SP) +, DO 

CMP.L WindowPReg, DO 

BEQ.S @1 


; clear room for result 
; get FrontWindow 
; Is front window pointer 
; same as our pointer? 

; Yes, call TextEdit 


; We weren't active, select our window. This causes an activate event. 


; PROCEDURE SelectWindow (theWindow: WindowPtr); 

MOVE.L WWindow, - (SP) ; Window Pointer To Stack 

SelectWindow ; Select Window 

BRA NextEvent ; and get next event 


@1 


; We were active, pass the click (with shift) to TextEdit. 

; PROCEDURE GlobalToLocal (VAR pt: Point); 

PEA Point ; Mouse Point 

_GlobalToLocal ; Global To Local 

; PROCEDURE TEClick (pt: Point; extend: BOOLEAN; hTE : TEHandle) ; 
MOVE.L Point, -(SP) ; Mouse Point (GTL) 

BTST #shiftKey, ModifyReg ; Is shift key down? 

SNE DO ; True if shift down 


; Note: We want the boolean in the high byte, so use MOVE.B. The 68000 
; pushes an extra, unused byte on the stack for us. 


MOVE.B 
MOVE . L 
TEClick 
BRA 


DO,- (SP) 
TextHReg,- (SP) 

NextEvent 


Identify Text 
TEClick 

Go get next event 


Drag 


; The click was in the drag bar of the window. Draggit. 


; DragWindow (theWindow : WindowPtr; 
MOVE.L WWindow, -(SP) 

MOVE.L Point, -(SP) 

PEA Bounds 

DragWindow 
BRA 


startPt: Point; boundsRect: Rect) ; 
; Pass window pointer 
; mouse coordinates 
; and boundaries 
; Drag Window 
; Go get next event 


NextEvent 
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InMenu 


; The click was in the menu bar. Determine which menu was selected, then 
; call the appropriate routine. 


; FUNCTION 
CLR.L 
MOVE . L 
MenuSelect 
MOVE 
MOVE 


MenuSelect (startPt : Point) : Longlnt; 

-(SP) ; Get Space For Menu Choice 

Point, -(SP) ; Mouse At Time Of Event 

; Menu Select 

(SP) +, MenuReg ; Save Menu 

(SP) +, MenuItemReg ; and Menu Item 


; On entry to Choices, the resource ID of the Menu is saved in the low 
; word of a register, and the resource ID of the Menultem in another. 

; The routine MenuKey, used when a command key is pressed, returns the same 
; info . 


Choices 


CMP 

BEQ 

CMP 

BEQ 

CMP 

BEQ 

ChoiceReturn 

BSR 

BRA 

InFileMenu 


#AppleMenu , MenuReg 
InAppleMenu 
#FileMenu, MenuReg 
InFileMenu 
#EditMenu, MenuReg 
InEditMenu 


Called by command key too 

Is It In Apple Menu? 

Go do Apple Menu 
Is It In File Menu? 

Go do File Menu 
Is It In Edit Menu? 

Go do Edit Menu 


UnHiliteMenu 

NextEvent 


Unhighlight the menu bar 
Go get next event 


; If it was in the File menu, just check for Quit since that's all there is. 


CMP #QuitItem, MenuItemReg ; Is It Quit? 

BNE.S ChoiceReturn ; No, Go get next event 

BSR UnHiliteMenu ; Unhiqhlight the menu bar 

MOVE #-l , DO ; say It was Quit 

RTS 


InEditMenu 


; First, call SystemEdit. If a desk accessory is active that uses the Edit 
; menu (such as the Notepad) this ltets it use our menu. 

; Decide whether it was cut, copy, paste, or clear. Ignore Undo since we 
; didn't implement it. 


BSR 

SystemEdit 

BNE.S 

ChoiceReturn 

CMP 

#CutItem, MenuItemReg 

BEQ 

Cut 

CMP 

#CopyItem, MenuItemReg 

BEQ 

Copy 

CMP 

#PasteItem, MenuItemReg 

BEQ 

Paste 

CMP 

#ClearItem, MenuItemReg 

BEQ 

Clear 

BRA.S 

ChoiceReturn 


Desk accessory active? 

Yes, SystemEdit handled it 
Is It Cut? 

Yes, go handle it 
Is it Copy? 

Yes, go handle it 
Is it Paste? 

Yes, go handle it 
Is it Clear? 

Yes, go handle it 
Go get next event 
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InAppleMenu 

; It was in the Apple menu. If it wasn't About, then it must have been a 
; desk accessory. If so, open the desk accessory. 


CMP #AboutItem, MenuItemReg ; Is It About? 

BEQ About ; If So Goto About... 


; PROCEDURE 

MOVE . L 

MOVE 

PEA 

Get Item 


Getltem (menu: MenuHandle; item: INTEGER; 

VAR itemString: Str255); 
AppleHReg, - (SP) ; Look in Apple Menu 

MenuItemReg, - (SP) ; What Item Number? 

DeskName ; Get Item Name 

; Get Item 


; FUNCTION 

CLR 

PEA 

OpenDeskAcc 

MOVE 


OpenDeskAcc 

"(SP) 

DeskName 

(SP) +, DO 


(theAcc : Str255) : INTEGER; 

; Space For Opening Result 
; Open Desk Acc 
; Open It 
; Pop result 


GoSetOurPort 


BSR SetOurPort 

BRA. S Choi ceRet urn 


Set port to us 
Unhilite menu and return 


Cut 


Text Editing Routines 
; CUT 


; PROCEDURE 
MOVE . L 
TECut 
BRA.S 


TECut (hTE : TEHandle); 

TextHReg, - (SP) ; Identify Text 

; Cut it and copy it 

ChoiceReturn ; Go get next event 


Copy 


COPY 


; PROCEDURE 
MOVE . L 
TECopy 
BRA. S 


TECopy (hTE: TEHandle); 
TextHReg,- (SP) 

ChoiceReturn ; 


Identify Text 

Copy text to clipboard 

Go get next event 


Paste 


PASTE 


; PROCEDURE 
MOVE . L 
TEPaste 
BRA. S 


TEPaste (hTE: TEHandle); 
TextHReg,- (SP) 

ChoiceReturn ; 


Identify Text 
Paste 

Go get next event 


Clear 


; PROCEDURE 
MOVE . L 
TEDelete 
BRA.S 


TEDelete (hTE: TEHandle); 

TextHReg, - (SP) ; Point to text 

; Clear without copying 
ChoiceReturn ; Go get next event 


; SystemEdit does undo, cut, copy, paste, and clear for desk accessories. 
; It returns False (BEQ) if the active window doesn't belong to a 
; desk accessory. 


SystemEdit 


; FUNCTION 
CLR 
MOVE 
SUBQ 
SysEdit 
MOVE . B 
RTS 


SystemEdit ( edit Cmd: INTEGER) : BOOLEAN; 

-(SP) ; Space for result 

MenuItemReg, - (SP) ; Get item in Edit menu 

#1, (SP) ; SystemEdit is off by 1 

; Do It 

(SP)+,D0 ; Pop result 

; BEQ if NOT handled 
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UnhiliteMenu 


; PROCEDURE 
CLR 

HiLiteMenu 

KTS 


HiLiteMenu (menuID: INTEGER); 

-(SP) ; All Menus 

; UnHilite Them All 


-Mi sc Routines 


About 


; Call GetNewDialog to read the dialog box parameters from the resource file 
; and display the box. Set the port to the box, then wait for the proper 
; click or keypress. Finally, close the dialog box and set the pointer to us. 


; FUNCTION 

CLR.L 
MOVE 
PEA 
MOVE . L 


GetNewDialog (dialogID: 

behind: 

~(SP) 

#AboutDialog, - (SP) ; 

DStorage ; 

#-l,-(SP) 


GetNewDialog 
MOVE . L (SP),-(SP) 


INTEGER; dStorage: Ptr; 

WindowPtr) : DialogPtr 
Space For dialog pointer 
Identify dialog rsrc # 
Storage area 
Dialog goes on top 
Display dialog box 
Copy handle for Close 


; PROCEDURE 
SetPort 


SetPort (gp: Graf Port) ; 


Handle already on stack 
Make dialog box the port 


; PROCEDURE TEDeActivate (hTE : TEHandle) 

MOVE . L TextHReg,- (SP) ; Identify Text 

TEDeActivate ; Deactivate Text 


Wait OK 


; PROCEDURE ModalDialog 


CLR.L -(SP) 

PEA ItemHit 

_ModalDialog 


(filterProc: ProcPtr; 

VAR itemHit: INTEGER); 

; Clear space For handle 
; Storage for item hit 
; Wait for a response 


MOVE 

CMP 

BNE 


ItemHit, DO 
#ButtonItem, DO 
Wait OK 


Look to see what was hit 
was it OK? 

No, wait for OK 


; PROCEDURE CloseDialog (theDialog: DialogPtr); 

_CloseDialog ; Handle already on stack 

BRA GoSetOurPort ' ; Set port to us and return 
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Data Starts Here 


EventRecord 



; NextEvent's Record 

What: 

DC 

0 

; Event number 

Message : 

DC . L 

0 

; Additional information 

When : 

DC . L 

0 

; Time event was posted 

Point : 

DC . L 

0 

; Mouse coordinates 

Modify: 

DC 

0 

; State of keys and button 

WWindow: 

DC . L 

0 

; Find Window' s Result 

DStorage 

DCB.W 

DWindLen, 0 

; Storage For Dialog 

DeskName 

DCB.W 

16, 0 

; Desk Accessory's Name 

Bounds 

DC 

28, 4,308,508 

; Drag Window' s Bounds 

ViewRect 

DC 

5,4,245,405 

; Text Record' s View Rect 

DestRect 

DC 

5,4,245,405 

; Text Record' s Dest Rect 

ItemHit 

DC 

0 

; Item clicked in dialog 


; Non relocatable Storage 

; Variables declared using DS are placed in a global space relative to 
; A5 . When these variables are referenced, A5 must be explicitly mentioned. 

WindowStorage DS.W WindowSize ; Storage for Window 

End 
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The Program 's Resource File 


* 

* This is the resource file for the example program called "Window" 

MDS2 : Window. Rsrc 

* 

* MENU Resource #1 specifies the menus used by the Window program. 

* For proper support of the Desk accessories, the Apple menu 

* should be first, and the Edit menu should be third. The first 5 items 

* in the Edit menu should be identical to those used below. This makes 

* it possible for the desk accessories to share the Edit menu with your 

* application. 

* 

Type MENU 
,1 
\14 

About This Example. . . 

<- 


, 2 
File 
Quit 


,3 

Edit 

(Undo/Z 

<- 

Cut/X 

Copy/C 

Paste/V 

Clear 

* Dialog Resource #1 specifies properties of the About box. It points 

* to Dialog Item List (DITL) Resource #1 as containing its items. 

Type DLOG 

,1 

100 100 190 400 
Visible NoGoAway 
1 
0 
1 

* Dialog Item List Resource #1 specifies the items in the About box. 

* By convention, the first item in an item list is the OK button. 

* If there is a cancel button, it should be second. This makes it 

* easier to interpret the item number returned by the call to ModalDialog. 

Type DITL 
,1 
3 

Button 

60 230 80 290 
OK 

StaticText 
15 20 36 300 

This sample program was written 

StaticText 
35 20 56 300 

just to prove it could be done ! 
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* WIND Resource #1 specifies the title, coordinates, and other status 

* for the window in which editing takes place. It is displayed by a 

* call to GetNewWindow . 

Type WIND 

,1 

A Sample 
50 40 300 450 
Visible NoGoAway 
0 
0 
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System Traps : Sorted by Name 

Here is an alphabetically sorted list of the Toolbox and Operating 
System traps and their trap numbers in hexadecimal. 

Make sure the names you use are the same as the names given here, 
names that differ when used from Pascal are marked by an asterisk. 


AddDrive 

$A04E 

ClosePort 

$A87D 

AddPt 

$A87E 

CloseResFile 

$A99A 

AddReference 

$A9AC 

CloseRgn 

$A8DB 

AddResMenu 

$A94D 

CloseWindow 

$A92D 

AddResource 

$A9AB 

Cmp String 

$A03C * 

Alert 

$A985 

ColorBit 

$A864 

Allocate 

$A010 * 

CompactMem 

$A04C 

AngleFromSlope 

$A8C4 

Control 

$A004 * 

AppendMenu 

$A933 

CopyBits 

$A8EC 

BackColor 

$A863 

CopyRgn 

$A8DC 

BackPat 

$A87C 

CouldAlert 

$A989 

BeginUpdate 

$A922 

CouldDialog 

$A979 

Bit And 

$A858 

CountMItems 

$A950 

BitClr 

$A85F 

CountResources 

$A99C 

BitNot 

$A85A 

CountTypes 

$A99E 

BitOr 

$A85B 

Create 

$A008 * 

BitSet 

$A85E 

CreateResFile 

$A9B1 

BitShift 

$A85C 

CurResFile 

$A994 

BitTst 

$A85D 

Date2Secs 

$A9C7 

BitXOr 

$A859 

Delay 

$A03B 

BlockMove 

$A02E 

Delete 

$A009 * 

BringToFront 

$A920 

DeleteMenu 

$A936 

Button 

$A974 

DeltaPoint 

$A94F 

CalcMenuSize 

$A948 

Dequeue 

$A96E 

CalcVBehind 

$A90A * 

DetachResource 

$A992 

CalcVis 

$A909 

DialogSelect 

$A980 

CautionAlert 

$A988 

DiffRgn 

$A8E6 

Chain 

$A9F3 

Disableltem 

$A93A 

ChangedResData 

$A9AA 

DisposControl 

$A955 * 

CharWidth 

$A88D 

DisposDialog 

$A983 * 

Checkltem 

$A945 

DisposeMenu 

$A932 

CheckUpdate 

$A911 

DisposHandle 

$A023 

ClearMenuBar 

$A934 

DisposPtr 

$A01F 

Cl ip Above 

$A90B 

DisposRgn 

$A8D9 * 

ClipRect 

$A87B 

DisposWindow 

$A914 * 

Close 

$A001 * 

DragControl 

$A967 

CloseDeskAcc 

$A9B7 

DragGrayRgn 

$A905 

CloseDialog 

$A982 

Drag The Rgn 

$A926 

ClosePgon 

$A8CC * 

DragWindow 

$A925 

ClosePicture 

$A8F4 

DrawChar 

$A883 


Trap 
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DrawControls 

$A969 

FreeAlert 

$A98A 

DrawDialog 

$A981 

FreeDialog 

$A97A 

DrawGrowIcon 

$A904 

FreeMem 

$A01C 

DrawMenuBar 

$A937 

FrontWindow 

$A924 

DrawNew 

$A90F 

GetAppParms 

$A9F5 

DrawPicture 

$A8F6 

GetClip 

$A87A 

DrawString 

$A884 

GetCRef Con 

$A95A 

DrawText 

$A885 

GetCTitle 

$A95E 

Drvr Ins tall 

$A03D * 

GetCtlAction 

$A96A 

Dr vr Remove 

$A03E * 

GetCtlValue 

$A960 

Eject 

$A017 * 

GetCursor 

$A9B9 

Empty Handle 

$A02B 

GetDItem 

$A98D 

EmptyRect 

$A8AE 

GetEOF 

$A01 1 * 

EmptyRgn 

$A8E2 

GetFilelnf o 

$A00C * 

Enableltem 

$A939 

GetFName 

$A8FF * 

EndUpdate 

$A923 

GetFNum 

$A900 

Enqueue 

$A96F 

GetFontlnf o 

$A88B 

EqualPt 

$A881 

GetFPos 

$A018 * 

EqualRect 

$A8A6 

GetHandleSize 

$A025 

EqualRgn 

$A8E3 

Get Icon 

$A9BB 

EraseArc 

$A8C0 

Get Ind Resource 

$A99D 

EraseOval 

$A8B9 

GetlndType 

$A99F 

ErasePoly 

$A8C8 

Getltem 

$A946 

EraseRect 

$A8A3 

GetIText 

$A990 

EraseRgn 

$A8D4 

Getltmlcon 

$A93F * 

EraseRoundRect 

$A8B2 

GetltmMark 

$A943 * 

Error Sound 

$A98C 

GetltmStyle 

$A941 * 

Event Avail 

$A971 

Get Keys 

$A976 

Exit To Shell 

$A9F4 

GetMaxCtl 

$A962 * 

FillArc 

$A8C2 

GetMenuBar 

$A93B 

FillOval 

$A8BB 

GetMHandle 

$A949 

FillPoly 

$A8CA 

GetMinCtl 

$A961 * 

FillRect 

$A8A5 

GetMouse 

$A972 

FillRgn 

$A8D6 

Ge t Named Re s our ce 

$A9A1 

FillRoundRect 

$A8B4 

GetNewControl 

$A9BE 

FindControl 

$A96C 

GetNewDialog 

$A97C 

FindWindow 

$A92C 

GetNewMBar 

$A9C0 

FixMul 

$A868 

GetNewWindow 

$A9BD 

FixRatio 

$A869 

GetNext Event 

$A970 

FixRound 

$A86C 

GetOSEvent 

$A031 

FlashMenuBar 

$A94C 

GetPattern 

$A9B8 

FlushEvents 

$A032 

Get Pen 

$A89A 

FlushFile 

$A045 * 

GetPenState 

$A898 

FlushVol 

$A013 * 

GetPicture 

$A9BC 

FMSwapFont 

$A901 * 

GetPixel 

$A865 

ForeColor 

$A862 

Get Port 

$A874 

Frame Arc 

$A8BE 

GetPtrSize 

$A021 

Frame Oval 

$A8B7 

GetResAttrs 

$A9A6 

Frame Poly 

$A8C6 

GetResFileAttrs 

$A9F6 

Frame Re ct 

$A8A1 

Get Res Info 

$A9A8 

Frame Rgn 

$A8D2 

GetResource 

$A9A0 

Frame Round Rect 

$A8B0 

GetRMenu 

$A9BF * 
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Get Scrap 

$A9FD 

InverRoundRec t 

$A8B3 * 

Get St ring 

$A9BA 

Invert Arc 

$A8C1 

Get Trap Address 

$A046 

Invert Oval 

$A8BA 

GetVol 

$A014 * 

InvertPoly 

$A8C9 

GetVolInfo 

$A007 * 

IsDialogEvent 

$A97F 

GetWindowPic 

$A92F 

KillControls 

$A956 

GetWMgrPort 

$A910 

KilllO 

$A006 * 

GetWRef Con 

$A917 

KillPicture 

$A8F5 

GetWTitle 

$A919 

KillPoly 

$A8CD 

Get Zone 

$A01A 

Launch 

$A9F2 

GlobalToLocal 

$A87 1 

Line 

$A892 

Graf Device 

$A872 

LineTo 

$A891 

GrowWindow 

$A92B 

LoadResource 

$A9A2 

HandAndHand 

$A9E4 

LoadSeg 

$A9F0 

Handle Zone 

$A026 

LocalToGlobal 

$A870 

HandToHand 

$A9E1 

LodeScrap 

$A9FB * 

HideControl 

$A958 

LongMul 

$A867 

HideCursor 

$A852 

LoWord 

$A86B 

HidePen 

$A896 

Map Poly 

$A8FC 

HideWindow 

$A916 

MapPt 

$A8F9 

HiliteControl 

$A95D 

MapRect 

$A8FA 

HiliteMenu 

$A938 

MapRgn 

$A8FB 

HiliteWindow 

$A91C 

MaxMem 

$A01D 

HiWord 

$A86A 

MenuKey 

$A93E 

HLock 

$A029 

MenuSelect 

$A93D 

HNo Purge 

$A04A 

ModalDialog 

$A991 

Home Res File 

$A9A4 

MoreMasters 

$A036 

HPurge 

$A049 

MountVol 

$A00F * 

HUnlock 

$A02A 

Move 

$A894 

InfoScrap 

$A9F9 

MoveControl 

$A959 

InitAllPacks 

$A9E6 

Move Port To 

$A877 

Ini tAppl Zone 

$A02C 

Move To 

$A893 

InitCursor 

$A850 

MoveWindow 

$A91B 

InitDialogs 

$A97B 

Munger 

$A9E0 

InitFonts 

$A8FE 

NewControl 

$A954 

InitGraf 

$A86E 

NewDialog 

$A97D 

Ini t Menus 

$A930 

NewHand le 

$A022 

Ini t Pack 

$A9E5 

NewMenu 

$A931 

Ini t Port 

$A86D 

NewPtr 

$A01E 

InitQueue 

$A016 

NewRgn 

$A8D8 

InitResources 

$A995 

NewString 

$A906 

InitUtil 

$A03F 

NewWindow 

$A913 

InitWindows 

$A912 

NoteAlert 

$A987 

Ini t Zone 

$A019 

ObscureCursor 

$A856 

InsertMenu 

$A935 

Offline 

$A035 * 

InsertResMenu 

$A951 

Of f setPoly 

$A8CE 

InsetRect 

$A8A9 

Off setRect 

$A8A8 

Inset Rgn 

$A8E1 

Of setRgn 

$A8E0 * 

InvalRect 

$A928 

Open 

$A000 * 

InvalRgn 

$ A927 

OpenDeskAcc 

$A9B6 

Inver Re ct 

$A8A4 * 

OpenPicture 

$A8F3 

Inver Rgn 

$A8D5 * 

OpenPoly 

$A8CB 
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OpenPort 

$A86F 

Rename 

$A00B * 

OpenResFile 

$A997 

ResError 

$A9AF 

OpenRF 

$A00A * 

ResrvMem 

$A040 

OpenRgn 

$A8DA 

Rmve Reference 

$A9AE 

OSEvent Avail 

$A030 

Rmve Re source 

$A9AD 

Pack0 

$A9E7 

RsrcZonelnit 

$A996 

Packl 

$A9E8 

RstFilLock 

$A042 * 

Pack2 

$A9E9 

Save Old 

$A90E 

Pack3 

$A9EA 

ScalePt 

$A8F8 

Pack4 

$A9EB 

ScrollRect 

$A8EF 

Pack5 

$A9EC 

Secs2Date 

$A9C6 

Pack6 

$A9ED 

Sect Rect 

$A8AA 

Pack 7 

$A9EE 

SectRgn 

$A8E4 

PackBits 

$A8CF 

SelectWindow 

$A91F 

Paint Arc 

$A8BF 

SellText 

$A97E 

PaintBehind 

$A90D 

Send Behind 

$A921 

Pa intOne 

$A90C 

SetAppBase 

$A857 * 

PaintOval 

$A8B8 

SetApplLimit 

$A02D 

PaintPoly 

$A8C7 

SetClip 

$A879 

PaintRect 

$A8A2 

SetCRefCon 

$A95B 

PaintRgn 

$A8D3 

SetCTitle 

$A95F 

Paint Round Rect 

$A8B1 

SetCtlAction 

$A96B 

ParamText 

$A98B 

SetCtlValue 

$A963 

PenMode 

$A89C 

SetCursor 

$A851 

PenNormal 

$A89E 

SetDateTime 

$A03A 

Pen Pat 

$A89D 

SetDItem 

$A98E 

PenSize 

$A89B 

Se t Empty Rgn 

$A8DD 

Pic Comment 

$A8F2 

Set EOF 

$A012 * 

PinRect 

$A94E 

SetFilelnfo 

$A00D * 

Plot Icon 

$A94B 

SetFilLock 

$A041 * 

PortSize 

$A876 

SetFilType 

$A043 * 

Post Event 

$A02F 

Set Font Lock 

$A903 

Pt2Rect 

$A8AC 

SetFPos 

$A044 * 

PtlnRect 

$A8AD 

SetGrowZone 

$A04B 

PtlnRgn 

$A8E8 

SetHandleSize 

$A024 

PtrAndHand 

$A9EF 

Set Item 

$A947 

PtrToHand 

$A9E3 

SetIText 

$A98F 

PtrToXHand 

$A9E2 

Setltmlcon 

$A940 * 

PtrZone 

$A048 

SetltmMark 

$A944 * 

PtToAngle 

$A8C3 

SetltmStyle 

$A942 * 

PurgeMem 

$A04D 

SetMaxCtl 

$A965 * 

PutScrap 

$A9FE 

SetMenuBar 

$A93C 

Random 

$A861 

SetMFlash 

$A94A * 

RDrvr Ins tall 

$A04F 

SetMinCtl 

$A964 * 

Read 

$A002 * 

SetOrigin 

$A878 

Re ad Date Time 

$A039 

SetPBits 

$A875 * 

RealFont 

$A902 

SetPenState 

$A899 

ReallocHandle 

$A027 

SetPort 

$A873 

RecoverHandle 

$A028 

SetPt 

$A880 

RectlnRgn 

$A8E9 

SetPtrSize 

$A020 

RectRgn 

$A8DF 

SetRecRgn 

$A8DE * 

ReleaseResource 

$A9A3 

SetRect 

$A8A7 
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SetResAttrs 

$A9A7 

TEActivate 

$A9D8 

SetResFileAttrs 

$A9F7 

TECalText 

$A9D0 

SetResInfo 

$A9A9 

TEClick 

$A9D4 

SetResLoad 

$A99B 

TECopy 

$A9D5 

Set Re sPurge 

$A993 

TECut 

$A9D6 

SetStdProcs 

$A8EA 

TEDeactivate 

$A9D9 

Set String 

$A907 

TEDelete 

$A9D7 

Set Trap Address 

$A047 

TEDispose 

$A9CD 

SetVol 

$A015 * 

TEGetText 

$A9CB 

SetWindowPic 

$A92E 

TEIdle 

$A9DA 

SetWRefCon 

$A918 

TEInit 

$A9CC 

SetWTitle 

$A91A 

TEInsert 

$A9DE 

Set Zone 

$A01B 

TEKey 

$A9DC 

ShieldCursor 

$A855 

TENew 

$A9D2 

ShowControl 

$A957 

TEPaste 

$A9DB 

ShowCursor 

$A853 

TEScroll 

$A9DD 

ShowHide 

$A908 

TESet Just 

$A9DF 

ShowPen 

$A897 

TESetSelect 

$A9D1 

ShowWindow 

$A915 

TESetText 

$A9CF 

SizeControl 

$A95C 

TestControl 

$A966 

SizeResource 

$A9A5 

TEUpdate 

$A9D3 

SizeWindow 

$A91D 

Text Box 

$A9CE 

SlopeFromAngle 

$A8BC 

TextFace 

$A888 

SpaceExtra 

$A88E 

TextFont 

$A887 

Status 

$A005 * 

Text Mode 

$A889 

StdArc 

$A8BD 

TextSize 

$A88A 

StdBits 

$A8EB 

TextWidth 

$A886 

StdComment 

$A8F1 

TickCount 

$A975 

StdGetPic 

$A8EE 

TrackControl 

$A968 

StdLine 

$A890 

TrackGoAway 

$A91E 

StdOval 

$A8B6 

UnionRect 

$A8AB 

StdPoly 

$A8C5 

UnionRgn 

$A8E5 

StdPutPic 

$A8F0 

Unique ID 

$A9C1 

StdRect 

$A8A0 

Unload Seg 

$A9F1 

StdRgn 

$A8D1 

UnlodeScrap 

$A9FA * 

StdRRect 

$A8AF 

Unmount Vol 

$A00E * 

StdText 

$A882 

UnpackBits 

$A8D0 

StdTxMeas 

$A8ED 

UpdateResFile 

$A999 

StillDown 

$A973 

UprString 

$A854 

StopAlert 

$A986 

UseResFile 

$A998 

StringWidth 

$A88C 

ValidRect 

$A92A 

Stuf fHex 

$A866 

ValidRgn 

$A929 

SubPt 

$A87F 

VInstall 

$A033 

SysBeep 

$A9C8 

V Re move 

$A034 

SysEdit 

$A9C2 * 

WaitMouseUp 

$A977 

SysError 

$A9C9 

Write 

$A003 * 

SystemClick 

$A9B3 

WriteParam 

$A038 

SystemEvent 

$A9B2 

WriteResource 

$A9B0 

SystemMenu 

$A9B5 

XOrRgn 

$A8E7 

SystemTask 

$A9B4 

ZeroScrap 

$A9FC 
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System Traps: Sorted by Number 

Here is an alphabetically sorted list of the Toolbox and Operating 


System traps, and their 

trap 

numbers in hexadecimal. 


Make sure the names you 

use 

are the same as 

the names given here. 

names 

that differ when i 

used 

from Pascal are 

marked by an asterisk 

$A 000 

Open 

* 

$A028 

Re cover Handle 


$A001 

Close 

* 

$A029 

HLock 


$A002 

Read 

* 

$A02A 

HUnlock 


$A003 

Write 

* 

$A02B 

Empty Handle 


$A004 

Control 

* 

$A02C 

Ini tAppl Zone 


$A005 

Status 

* 

$A02D 

SetApplLimit 


$A006 

Kill 10 

* 

$A02E 

BlockMove 


$A007 

GetVolInfo 

* 

$A02F 

PostEvent 


$A008 

Create 


$A030 

OSEvent Avail 


$A009 

Delete 


$A031 

GetOSEvent 


$A00A 

OpenRF 

* 

$A032 

FlushEvents 


$A00B 

Rename 

* 

$A033 

VInstall 


$A00C 

GetFilelnf o 

* 

$A034 

VRemove 


$A00D 

SetFilelnfo 

* 

$A035 

Offline 

* 

$A00E 

UnmountVol 

* 

$A036 

MoreMasters 


$A00F 

MountVol 

* 

$A038 

WriteParam 


$A010 

Allocate 

* 

$A039 

ReadDateTime 


$A01 1 

GetEOF 

* 

$A03A 

SetDateTime 


$A012 

SetEOF 

* 

$A03B 

Delay 


$A013 

FlushVol 

* 

$A03C 

Cmp String 

* 

$A014 

GetVol 

* 

$A03D 

Drvr Ins tall 

* 

$A015 

SetVol 

* 

$A03E 

DrvrRemove 

it 

$A016 

Ini t Queue 


$A03F 

InitUtil 


$A017 

Eject 

* 

$A040 

ResrvMem 


$A018 

GetFPos 

* 

$A041 

SetFilLock 

it 

$A019 

Ini t Zone 


$A042 

RstFilLock 

* 

$A01A 

Get Zone 


$A043 

SetFilType 

* 

$A01B 

Set Zone 


$A044 

SetFPos 

* 

$A01C 

FreeMem 


$A045 

FlushFile 

* 

$A01D 

MaxMem 


$A046 

Get Trap Address 


$A01E 

NewPtr 


$A047 

Set Trap Address 


$A01F 

DisposPtr 


$A048 

PtrZone 


$A020 

SetPtrSize 


$A049 

HPurge 


$A021 

GetPtrSize 


$A04A 

HNoPurge 


$A022 

NewHandle 


$A04B 

SetGrowZone 


$A023 

DisposHandle 


$A04C 

CompactMem 


$A024 

SetHandleSize 


$A04D 

PurgeMem 


$A025 

GetHandleSize 


$A04E 

Add Drive 


$A026 

HandleZone 


$A04F 

RDrvr Install 


$A027 

ReallocHandle 


$A850 

InitCursor 



Trap 
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$A851 

SetCursor 

$A852 

HideCursor 

$A853 

ShowCursor 

$A854 

UprString 

$A855 

ShieldCursor 

$A856 

ObscureCursor 

$A857 

SetAppBase 

$A858 

Bit And 

$A859 

BitXOr 

$A85A 

BitNot 

$A85B 

Bit Or 

$A85C 

BitShift 

$A85D 

BitTst 

$A85E 

BitSet 

$A85F 

BitClr 

$A861 

Random 

$A862 

ForeColor 

$A863 

BackColor 

$A864 

ColorBit 

$A865 

GetPixel 

$A866 

Stuff Hex 

$A867 

LongMul 

$A868 

FixMul 

$A869 

FixRatio 

$A86A 

HiWord 

$A86B 

LoWord 

$A86C 

FixRound 

$A86D 

InitPort 

$A86E 

InitGraf 

$A86F 

OpenPort 

$A870 

LocalToGlobal 

$A871 

GlobalToLocal 

$A872 

Graf Device 

$A873 

SetPort 

$A874 

GetPort 

$A875 

SetPBits 

$A876 

PortSize 

$A877 

MovePortTo 

$A878 

SetOrigin 

$A879 

SetClip 

$A87A 

GetClip 

$A87B 

ClipRect 

$A87C 

BackPat 

$A87D 

ClosePort 

$A87E 

AddPt 

$A87F 

SubPt 

$A880 

SetPt 

$A881 

EqualPt 

$A882 

StdText 

$A883 

DrawChar 

$A884 

DrawString 

$A885 

DrawText 


$A886 

TextWidth 

$A887 

TextFont 

$A888 

Text Face 

$A889 

TextMode 

$A88A 

Text Size 

$A88B 

Get Font Info 

$A88C 

StringWidth 

$A88D 

CharWidth 

$A88E 

SpaceExtra 

$A890 

StdLine 

$A891 

LineTo 

$A892 

Line 

$A893 

Move To 

$A894 

Move 

$A896 

Hide Pen 

$A897 

ShowPen 

$A898 

GetPenState 

$A899 

SetPenState 

$A89A 

Get Pen 

$A89B 

PenSize 

$A89C 

PenMode 

$A89D 

PenPat 

$A89E 

PenNormal 

$A8A0 

StdRect 

$A8A1 

FrameRect 

$A8A2 

PaintRect 

$A8A3 

EraseRect 

$A8A4 

InverRect * 

$A8A5 

FillRect 

$A8A6 

EqualRect 

$A8A7 

SetRect 

$A8A8 

Of f setRect 

$A8A9 

InsetRect 

$A8AA 

SectRect 

$A8AB 

UnionRect 

$A8AC 

Pt2Rect 

$A8AD 

PtlnRect 

$A8AE 

EmptyRect 

$A8AF 

StdRRect 

$A8B0 

Frame RoundRect 

$A8B1 

Paint Round Re ct 

$A8B2 

EraseRoundRect 

$A8B3 

InverRoundRect * 

$A8B4 

FillRoundRect 

$A8B6 

StdOval 

$A8B7 

Frame Oval 

$A8B8 

PaintOval 

$A8B9 

EraseOval 

$A8BA 

Invert Oval 

$A8BB 

FillOval 

$A8BC 

Slope FromAngle 

$A8BD 

StdArc 
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$A8BE 

Frame Arc 

$A8F3 

OpenPicture 

$A8BF 

PaintArc 

$A8F4 

ClosePicture 

$A8C0 

EraseArc 

$A8F5 

KillPicture 

$A8C1 

Invert Arc 

$A8F6 

DrawPicture 

$A8C2 

FillArc 

$A8F8 

ScalePt 

$A8C3 

PtToAngle 

$A8F9 

MapPt 

$A8C4 

AngleFromSlope 

$A8FA 

MapRect 

$A8C5 

StdPoly 

$A8FB 

MapRgn 

$A8C6 

Frame Poly 

$A8FC 

Map Poly 

$A8C7 

PaintPoly 

$A8FE 

InitFonts 

$A8C8 

ErasePoly 

$A8FF 

GetFName 

$A8C9 

InvertPoly 

$A900 

GetFNum 

$A8CA 

FillPoly 

$A901 

FMSwapFont 

$A8CB 

OpenPoly 

$A902 

Real Font 

$A8CC 

ClosePgon * 

$A903 

Set Font Lock 

$A8CD 

KillPoly 

$A904 

DrawGrowIcon 

$A8CE 

Of f setPoly 

$A905 

DragGrayRgn 

$A8CF 

PackBits 

$A906 

NewString 

$A8D0 

UnpackBits 

$A907 

SetString 

$A8D1 

StdRgn 

$A908 

ShowHide 

$A8D2 

Frame Rgn 

$A909 

CalcVis 

$A8D3 

PaintRgn 

$A90A 

CalcVBehind 

$A8D4 

EraseRgn 

$A90B 

Cl ip Above 

$A8D5 

Inver Rgn * 

$A90C 

Pa intOne 

$A8D6 

FillRgn 

$A90D 

PaintBehind 

$A8D8 

NewRgn 

$A90E 

Save Old 

$A8D9 

DisposRgn 

$A90F 

DrawNew 

$A8DA 

OpenRgn 

$A910 

GetWMgrPort 

$A8DB 

CloseRgn 

$A911 

CheckUpdate 

$A8DC 

CopyRgn 

$A912 

InitWindows 

$A8DD 

Set Empty Rgn 

$A913 

NewWindow 

$A8DE 

SetRecRgn * 

$A914 

DisposWindow 

$A8DF 

RectRgn 

$A915 

ShowWindow 

$A8E0 

Of set Rgn * 

$A916 

HideWindow 

$A8E1 

InsetRgn 

$A917 

GetWRefCon 

$A8E2 

Empty Rgn 

$A918 

SetWRefCon 

$A8E3 

EqualRgn 

$A919 

GetWTitle 

$A8E4 

Sect Rgn 

$A91A 

SetWTitle 

$A8E5 

UnionRgn 

$A91B 

MoveWindow 

$A8E6 

DiffRgn 

$A91C 

HiliteWindow 

$A8E7 

XOrRgn 

$A91D 

SizeWindow 

$A8E8 

Pt InRgn 

$A91E 

TrackGoAway 

$A8E9 

Re c tin Rgn 

$A91F 

SelectWindow 

$A8EA 

SetStdProcs 

$A920 

BringToFront 

$A8EB 

StdBits 

$A921 

Send Behind 

$A8EC 

Copy Bits 

$A922 

BeginUpdate 

$A8ED 

StdTxMeas 

$A923 

EndUpdate 

$A8EE 

StdGetPic 

$A924 

FrontWindow 

$A8EF 

ScrollRect 

$A925 

DragWindow 

$A8F0 

StdPutPic 

$A926 

DragTheRgn 

$A8F1 

StdComment 

$A927 

InvalRgn 

$A8F2 

PicComment 

$A928 

InvalRect 
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$A929 

ValidRgn 


$A92A 

ValidRect 


$A92B 

GrowWindow 


$A92C 

FindWindow 


$A92D 

CloseWindow 


$A92E 

SetWindowPic 


$A92F 

GetWindowPic 


$A930 

Ini tMenus 


$A931 

NewMenu 


$A932 

DisposeMenu 


$A933 

AppendMenu 


$A934 

ClearMenuBar 


$A935 

InsertMenu 


$A936 

DeleteMenu 


$A937 

DrawMenuBar 


$A938 

HiliteMenu 


$A939 

Enable Item 


$A93A 

Disableltem 


$A93B 

GetMenuBar 


$A93C 

Set Menu Bar 


$A93D 

MenuSelect 


$A93E 

MenuKey 


$A93F 

Getltmlcon 

* 

$A940 

Setltmlcon 

* 

$A941 

GetltmStyle 

* 

$A942 

SetltmStyle 

* 

$A943 

GetltmMark 

* 

$A944 

SetltmMark 

* 

$A945 

Checkltem 


$A946 

Getltem 


$A947 

Set Item 


$A948 

CalcMenuSize 


$A949 

GetMHandle 


$A94A 

SetMFlash 

* 

$A94B 

Plot Icon 


$A94C 

FlashMenuBar 


$A94D 

AddResMenu 


$A94E 

PinRect 


$A94F 

DeltaPoint 


$A950 

CountMItems 


$A951 

InsertResMenu 


$A954 

NewControl 


$A955 

DisposControl 


$A956 

KillControls 


$A957 

ShowControl 


$A958 

HideControl 


$A959 

MoveControl 


$A95A 

GetCRefCon 


$A95B 

SetCRef Con 


$A95C 

SizeControl 


$A95D 

HiliteControl 


$A95E 

GetCTitle 



$A95F 

SetCTitle 


$A960 

GetCtlValue 


$A961 

GetMinCtl 

* 

$A962 

GetMaxCtl 

* 

$A963 

SetCtlValue 


$A964 

SetMinCtl 

* 

$A965 

SetMaxCtl 

* 

$A966 

TestControl 


$A967 

DragControl 


$A968 

TrackControl 


$A969 

DrawControls 


$A96A 

GetCtlAction 


$A96B 

SetCtlAction 


$A96C 

FindControl 


$A96E 

Dequeue 


$A96F 

Enqueue 


$A970 

GetNext Event 


$A971 

Event Avail 


$A972 

GetMouse 


$A973 

StillDown 


$A974 

Button 


$A975 

TickCount 


$A976 

GetKeys 


$A977 

WaitMouseUp 


$A979 

CouldDialog 


$A97A 

FreeDialog 


$A97B 

InitDialogs 


$A97C 

GetNewDialog 


$A97D 

NewDialog 


$A97E 

SellText 


$A97F 

IsDialogEvent 


$A980 

DialogSelect 


$A981 

DrawDialog 


$A982 

CloseDialog 


$A983 

DisposDialog 


$A985 

Alert 


$A986 

StopAlert 


$A987 

NoteAlert 


$A988 

CautionAlert 


$A989 

CouldAlert 


$A98A 

FreeAlert 


$A98B 

ParamText 


$A98C 

Error Sound 


$A98D 

GetDItem 


$A98E 

SetDItem 


$A98F 

SetIText 


$A990 

GetIText 


$A991 

ModalDialog 


$A992 

DetachResource 


$A993 

Set Re sPurge 


$A994 

Cur Res File 


$A995 

InitResources 
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$A996 

RsrcZone Init 

$A9CD 

TEDispose 

$A997 

OpenResFile 

$A9CE 

TextBox 

$A998 

UseResFile 

$A9CF 

TESetText 

$A999 

UpdateResFile 

$A9D0 

TECalText 

$A99A 

CloseResFile 

$A9D1 

TESetSelect 

$A99B 

Set Res Load 

$A9D2 

TENew 

$A99C 

CountResources 

$A9D3 

TEUpdate 

$A99D 

Get Ind Resource 

$A9D4 

TEClick 

$A99E 

Count Types 

$A9D5 

TECopy 

$A99F 

Get Ind Type 

$A9D6 

TECut 

$A9A0 

GetResource 

$A9D7 

TEDelete 

$A9A1 

Ge t Name d Re source 

$A9D8 

TEActivate 

$A9A2 

LoadResource 

$A9D9 

TEDeactivate 

$A9A3 

ReleaseResource 

$A9DA 

TEIdle 

$A9A4 

Home Res File 

$A9DB 

TEPaste 

$A9A5 

SizeResource 

$A9DC 

TEKey 

$A9A6 

GetResAttrs 

$A9DD 

TEScroll 

$A9A7 

SetResAttrs 

$A9DE 

TE Insert 

$A9A8 

Get Res Info 

$A9DF 

TESet Just 

$A9A9 

SetResInfo 

$A9E0 

Munger 

$A9AA 

ChangedResData 

$A9E1 

Hand To Hand 

$A9AB 

AddResource 

$A9E2 

PtrToXHand 

$A9AC 

AddReference 

$A9E3 

PtrToHand 

$A9AD 

RmveResource 

$A9E4 

Hand And Hand 

$A9AE 

Rmve Reference 

$A9E5 

Init Pack 

$A9AF 

ResError 

$A9E6 

InitAllPacks 

$A9B0 

WriteResource 

$A9E7 

Pack0 

$A9B1 

CreateResFile 

$A9E8 

Packl 

$A9B2 

SystemEvent 

$A9E9 

Pack2 

$A9B3 

SystemClick 

$A9EA 

Pack 3 

$A9B4 

SystemTask 

$A9EB 

Pack4 

$A9B5 

SystemMenu 

$A9EC 

Pack5 

$A9B6 

OpenDeskAcc 

$A9ED 

Pack6 

$A9B7 

CloseDeskAcc 

$A9EE 

Pack7 

$A9B8 

GetPattern 

$A9EF 

PtrAndHand 

$A9B9 

GetCursor 

$A9F0 

LoadSeg 

$A9BA 

GetString 

$A9F1 

Unload Seg 

$A9BB 

Getlcon 

$A9F2 

Launch 

$A9BC 

GetPicture 

$A9F3 

Chain 

$A9BD 

GetNewWindow 

$A9F4 

Exit To Shell 

$A9BE 

GetNewControl 

$A9F5 

GetAppParms 

$A9BF 

GetRMenu * 

$A9F6 

Get Res File At trs 

$A9C0 

GetNewMBar 

$A9F7 

SetResFileAttrs 

$A9C1 

Unique ID 

$A9F9 

Info Scrap 

$A9C2 

SysEdit * 

$A9FA 

Unlode Scrap 

$A9C6 

Secs2Date 

$A9FB 

Lode Scrap 

$A9C7 

Date2Secs 

$A9FC 

Zero Scrap 

$A9C8 

SysBeep 

$A9FD 

Get Sc rap 

$A9C9 

SysError 

$A9FE 

Put Scrap 

$A9CB 

TEGetText 

$A9FF 

Debugger 


$A9CC TEInit 
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Assembler Error Messages 

Here is a list of the error messages that can be displayed by the 
Assembler. A brief description accompanies the messages that are not 
entirely self-explanatory. 

Absolute expression required 

Character literal size error: Character literals must be from 1 to 4 
characters long. 

Could not open 

Could not open error file: 

Could not open file: 

Could not open file name list file: Could not open a .Files file. 

Disk full 

Disk I/O error 

Disk write-protected 

ELSE out of context: Only occurs in an IF statement. 

Expression must be constant 
Fatal assembly error: 

File name too long: The symbol is longer than 252 characters. 

File open error 
Illegal .ALIGN value 
Illegal .DUMP file name 

Illegal expression follows #: For example, #D0. 

Illegal expression operand in EA: The operand used in the effective 
address field is illegal. 

Illegal formal not declared 
Illegal INCLUDE file name 

Illegal index size: For example, 274(A0,D0). 

Illegal indexing: For example 23(D0,D1). 

Illegal line: The Assembler could not recognize the line as anything. 

Often caused by missing semicolon on comment line. 

Illegal number: For example, an octal number with an 8 in it. 

Illegal opcode name 

Illegal opcode size tag: One of the extensions .B, .W, or .L was not 
used in the proper context. 

Illegal operand 

Illegal operand /operator combination: This is a general error message. 

Caused, for example, by MOVE.L D0,34(PC). 

Illegal operator 

Illegal or missing operand(s) for instruction: For example, PEA D0. 

Illegal register list 

Illegal relocation in expression 

Illegal RESOURCE directive 

Illegal string comparison: Only occurs in an IF statement. 

Illegal symbol type : 

Illegal trap definition 
I/O memory error 
Macro definition error 
Macro too long 
Missing <char> 

Missing ENDIF: Only occurs in an IF statement. 

Missing formal in macro 
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Missing formal in macro definition or call 

Missing macro definition body 

Missing operand 

Missing operator 

Missing string literal 

Multiply defined label: The specified label was previously declared. 
Multiply defined symbol 
<Name> redefined 

Not enough room for...: Occurs when loading packed symbols. 

Number expected: This message comes from a macro definition. 

Number too long: The symbol is longer than 252 characters. 

Out of memory: Probably symbol table full or MacsBug installed. 

Partial field error in macro formal 

PC relative address out of range: This is usually caused by a short PC 
relative reference backward to a label that is too far away. 

Register list expected 

Size mismatch for operator /operands : The size of the operand does not 
match the size of the operator (plus .B, .W, or .L). 

Stopped by user : Either the Stop button was clicked or Command -period 
was pressed. 

String overflow: The symbol is longer than 252 characters. 

String too long: The symbol is longer than 252 characters. 

Symbol too long: The symbol is longer than 252 characters. 

Too many formals in macro 
Too many levels of macro nesting 
Too many nested files 
Undefined label: 

Unknown cause: This is a serious error of unknown origin. Assembly 
is abandoned when it occurs. 

Unknown directive: Didn’t recognize the directive. 

Unknown I/O error 

Unmatched ELSE or ENDIF: Only occurs in an IF statement. 

Value out of range : This is usually caused by a short PC relative 
reference backward to a label that is too far away. 

Volume locked 

Warning: .S operand out of range: .W assumed: This is a warning 
only. 

XREF symbol defined: This message is a warning only. 
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Linker Error Messages 


Here is a list of the error messages that can be displayed by the 
Linker . 

Code segments cannot follow resources 
Could not create resource 
Could not open file: 

Could not open .Rel file: 

Could not open resource file 
Could not open temp file 
Disk full 
Disk I/O error 
Disk write-protected 

Duplicate Ident (System Error) 

Duplicate symbol 

Error in control file: Unknown type or error message 

Errors in linking 

Extra characters on line 

File locked 

File name too long: The symbol is longer than 252 characters. 
File open error 
Illegal / command 
Illegal input token 
Illegal number 
Illegal .Rel file name 
Illegal starting label 
Illegal symbol Ident 
Invalid or missing .Rel file 
I/O memory error 

JTSize does not match global size 
JTSize does not match symbol count 
Link errors 
Linker error . . • 

Missing Ident 
Multiply defined symbol: 

Not enough memory to create resource: 

Number too long: The symbol is longer than 252 characters. 

Out of memory 

RESOURCE directive in file before /RESOURCES 
Segments cannot follow resources 
Source file open fail: 

Stack overflow (System Error) 

Stack underflow (System Error) 

Start label not found: 

Start label undefined 
String overflow 

Symbol too long: The symbol is longer than 252 characters. 

Symbol not found : 

Unknown arith opcode = (System Error) 

Unknown cause 
Unknown I/O error 
Unknown opcode = 


(System Error) 

(System Error) 

(System Error) 
(System Error) 

(System Error) 


(System Error) 
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Undefined external: 

Volume locked 

Value or offset out of range: 

Expected a value between xx and yy. 
Actual value was zz. 
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RMaker Error Messages 

Here is a list of the error messages that can be displayed by RMaker. 

A brief description accompanies the messages that are not entirely 
self-explanatory • 

An Input/Output error has occurred 
Bad attributes parameter 
Bad bundle definition 
Bad format number 

Bad format resource designator in GNRL type: This is any error in 
a user-defined resource type. 

Bad ID Number 
Bad item type 

Bad object definition: This can happen if the specified file is of the 
wrong type. 

Bad type or item declaration 

Can’t add to the file — disk protected or full? 

Can’t create the output file 
Can’t load INCLUDE file 
Can’t open the output file 
Out of memory 

Syntax error in source file 

Unknown type: The specified resource type is not defined. 
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Registers : D0 . . D7 
A0..A7 
A7 or SP 
SR 
CCR 
PC 


Data Registers 0 through 7 
Address Registers 0 through 7 
Stack Pointer 
Status Register 
Condition Code Register 
Program Counter 


For MOVEM: for register range; 1 /* for list. Example: A1-A4/D0/D6 


Syntax 
An or Dn 
(An) 

(An)+ 

-(An) 

Expr( An) 

Expr( An, An) 

Expr(An,Dn) 

Expr 

Expr(PC) 

Expr(PC,An) 

Expr(PC,Dn) 

Expr(Dn) 

//Expr 


Addressing mode 

Register Direct 

Register Indirect 

Postincrement Register Indirect 

Predecrement Register Indirect 

Register Indirect with Offset 

Indexed Register Indirect with Offset 

Indexed Register Indirect with Offset 

Absolute or Relative 

Relative with Offset 

Relative with Index and Offset 

Relative with Index and Offset 

Relative with Index and Offset 

Immediate 


.B 

.W 

.L 


Operands are one byte long 
Operands are one word long (2 bytes) 
Operands are long words (4 bytes) 


Bcc.S Short branch (long is default) 

JMP.W Short jump (long is default) 


Numbers : Decimal is default; $ for hex; ~ for octal; % for binary. 


Strings : Enclosed in single quotes. Use two single quotes in a row to 
put a single quote in a string. 


Symbols : Start with , A , -*Z , > 'a'-'z', •_* 

Followed by 'A'-'Z 1 , 'a'-'z', '0'-'9', 


»i i6i ii 
• J V > • 


Operators : 


Arithmetic 

Addition 

+ 



Subtraction 

- 



Multiplication 

* 



Division 

/ 

Integer result 


Negation 

- 


Shift 

Shift Right 

» 

Zeros shifted in 


Shift Left 

« 

Zeros shifted in 

Logical 

And 

& 



Or 

I 
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Precedence : 


1 . Operations within parentheses (innermost first) 

2. Negation 

3. Shift operations 

4. Logical operations 

5. Multiplication and division 

6. Addition and subtraction 


Assembler Directives : 

INCLUDE filename 
STRING_FORMAT value 

General Strings : value = 0 
value = 1 

DC .x Strings: value = 0 

value = 2 


value = 

IF condition. . .ELSE. . .ENDIF 

MACRO 

name Pl,P2,...Pn 

END 

.DUMP 

EQU 

XXXX {PI } , {P2 } 

YYYY {Pn} 

1 

expression 

SET 

expression 

REG 

register list 

.TRAP 

name $Axxx 

DC. B 

value (s ) 

DC 

value(s) 

DC .W 

value ( s ) 

DC.L 

value(s) 

DS.B 

length 

DS 

length 

DS.W 

length 

DS.L 

length 

DCB.B 

length, value 

DCB 

length, value 

DCB.W 

length, value 

DCB.L 

length, value 

.ALIGN 

value 

XDEF 

symbol(s) 

XREF 

symbol (s ) 


RESOURCE type ID [name [attr]] 

.NoList 

•ListToFile 

•ListToDisp 

•Verbose 

•No Verbose 


Include source file 
Set string format 
Text followed by a 0 byte 
Text preceded by a count byte 
Write strings literally 
Text preceded by a count byte 
Specifies 1 and 2 
Conditional assembly 

Mac-style macro definitions. 

Arguments are symbols, defined 
after name. 


End of program 

Dump symbols to . Syra file 

Set permanent constant 

Set temporary constant 

Define register list 

Assign a name to trap number $Axxx 

Define Constant 

values are separated by commas 


Define Storage 


Define Constant Block 


value = 2 for word alignment 

value = 4 for long word alignment 

Symbol used externally 

Symbol defined externally 

Begin resource definition 

Turn off listing 

Turn on listing to file 

Turn on listing to display 

Turn on verbose listing which is 

needed for Linker listing 

Turn off verbose listing 
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filename 
! label 
< 

[ 

] 

( 

) 

/Verbose 
/NoVerbose 
/ Unde f OK 
/NoUndef 
/Type 
/Globals 
/ Output 
/Resources 
/Data 
$ 


The next file to link is the file named filename .Rel 

Make label the starting location for the program 

Start a new segment 

Turn on code listing to .Map file 

Turn off code listing to .Map file 

Turn off listing of local labels to .Map file 

Turn on listing of local labels to .Map file 

Turn on verbose linker output 

Turn off verbose linker output 

Give warning only for undefined symbols 

Give fatal errors for undefined symbols 

Set type and creator bytes for file 

Set offset from A5 of start of global space 

Specify name of output file 

Code section done; begin resource section 

Resource section done; begin data section 

End of Linker control file 
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Serial Cable Connections 


These two diagrams illustrate the connections necessary to use MacDB 
with two Macintoshes or with a Macintosh and a Lisa. These allow you 
to build your own cables for use with the Debugger. 


Macintosh to Macintosh Serial Cable 


1 Mac Serial Port 
DB-9 

Mac Serial Port 
DB-9 

No connect 

1 


1 

No connect 

No connect 

2 


2 

No connect 

Ground 

3 


3 

Ground 

TXD+ 

4 

t M 

4 

TXD+ 

TXD- 

5 


5 

TXD- 

No Connect 

6 


6 

No Connect 

Handshake 

7 


7 

Handshake 

1 RXD+ 

8 


8 

RXD+ 

RXD- 

9 


9 

RXD- 


Macintosh to Lisa Serial Cable 


Mac Serial Port 

Lisa Serial Port ! 

DB-9 

DB-25 


Ground 
No connect 
Ground 
TXD+ 
TXD- 
No Connect 
Clock 
RXD+ 
RXD- 
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Numbers : 
Text : 
Symbols : 
Operators : 


$ means hex; & means decimal. Maximum size is long word 
One to four characters enclosed in single quotes. 

RA0 • .RA7 ,RD0 • .RD7 , PC , SP,TP, * . 1 (dot=current address) 

+ (addition), - (subtraction, negation), @ (indirection) 


Memory Commands 

DM A N Display N bytes of memory starting at address A 

If N = * IOPB f , *WIND 1 , f TERC 1 , displays data structure 
SM A El..En Set memory values El through En starting at address A 


Dn E 
An E 
PC E 
SR E 
TD 


Register Commands 

Set data register n to E. If E is omitted, display n 
Set address register n to E. If E is omitted, display n 
Set the PC to value E. If E is omitted, display the PC 
Set the SR to value E. If E is omitted, display the SR 
Display all the registers 


BR A C 

CL A 
G A 
GT A 
T 

S N 

SS A1 A2 


ST A 
MR N 


RB 

ES 


Control Commands 

Set breakpoint at address A. Do C times before breaking. 
C is optional 

Clear breakpoint at address A. If A omitted, clear all 
Execute application starting at A. If no A, at current PC 
Set one-time breakpoint at address A, start at current PC 
Trace one instr. Traps treated as single instructions 
Step through N instructions. If N is omitted, one 
instruction is executed. Traps not single instructions 
Remember checksum for address range; step through 
instructions, validating checksum before each one; break 
into MacsBug if checksum changes 

Step through instructions to address A. A can be in ROM 
Execute instructions until return address N bytes down in 
stack is used. If N is omitted, return address on top of 
stack is used 
Reboot Macintosh 

Exit to the shell; launch startup application 


A-Trap Commands 

Take effect if a trap in the range T1 through T2 is called from address 
range A1 through A2 , and D0 has a value between D1 and D2. For omitted 
parameters, full range (all traps, all addresses, all D0 values) used. 
These commands set up conditions that are monitored when Go is used. 


AB T1 T2 A1 A2 D1 D2 

AT T1 T2 A1 A2 D1 D2 

AH T1 T2 A1 A2 Dl D2 

HS T1 T2 

AS A1 A2 

AX 


Break on specified A-traps 

Trace program and display specified A-traps 
Check the heap on specified traps 
Scramble heap and check it on specified traps 
Usually Tl=$18 and T2=$2D for optimal speed 
Remember checksum for address range; validate it 
before traps 

Clear all A-Trap commands 
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Heap Commands 

HX Toggle between system heap and application heap 

HC Check the consistency of current heap 

HD MASK Dump each heap block, followed by heap summary line 

Block = BlockAddr Type Size [Flags MP_location] [*] [RefNum ID Type] 

Type (of block): F = free, P = pointer, H = handle 

Size: physical size = header+contents+spare bytes 

Flags nibble: Bit 3 = Locked; Bit 2 = Purgeable; 

Bit 1 = Resource; Bit 0 = unused 
MP_Location: the location of the Master Pointer 

*: indicates non-relocatable or locked blocks 

RefNum ID Type : given for resource blocks only 

If no MASK: 

Summary = HLP PF // Reloc blocks, //Locked reloc blocks, # Purgeable blocks, 
Purgeable space, Non-reloc blocks, Free Space 

If MASK = *H f (handle), 'P 1 (pointer), f F f (free blocks), 

, R* (relocatable), or ‘xxxx 1 (resource type 'xxxx’) then 
Summary = CNT ##// <# of blocks of MASK type> <// bytes in those blocks> 

HP MASK Dump heap to other port (TermBugA or TermBugB only) 

HT MASK Display heap dump summary line (See HD) 

Disassembler Commands 

ID A Disassemble one line at address A 

IL A N Disassemble N lines starting at address A 

PX Toggles symbolic display (Pascal option only) 

Miscellaneous Commands 

F A C D M Search C bytes from address A, looking for data D after 

masking the target with M. Display first occurrence 
WH X X<512: display address of trap X 

X>511: display trap nearest address X 
CS A1 A2 Checksum specified range. If no A2, 16 bytes. If no A1 

or A2, checksum and compare with last. Print result. 

CV X Display X as unsigned hex, signed hex, signed decimal 

and text 

RX Toggle register display during trace 


SM PC 60FE 
SM PC 4E71 


Handy Hints 

Enter instruction BRA *-2 to stop disk spinning 


Enter no-op at current PC location 
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Glossary 


The terms in this glossary are defined in the context of the Macintosh 
68000 Development System. All references to the Assembler, Editor, 
Linker, RMaker, or PackSyms refer to applications in the development 
system. Things that are true of the Editor, Assembler, or Linker in 
this package are not necessarily true of other editors, assemblers, or 
linkers . 


application: A tool to manipulate information. Macintosh 68000 
Development System applications include the Editor, Assembler, Linker, 
Executive, Resource Compiler, and PackSyms. 

application heap: A portion of memory available to the application 
program for its own memory allocation. 

argument: In a macro definition, a placeholder for values that are 

supplied when the macro is actually used. Values are passed to the 
macro as a list of parameters; they replace, character-f or-character , 
the arguments that represent them. 

assembler: An application that translates an assembly-language program 

(understandable by humans) into a form that is useful to a computer. 

The Assembler creates modules that can then be connected together, by 
the Linker, to form an application. 

assembly-language program: Lines of text containing instructions 
written by a human, translated by an assembler, and carried out by a 
computer. These instructions generally include instructions to the 
microprocessor, instructions to the assembler, and comments to humans. 

A-trap: An instruction beginning with a hexadecimal $A which, when 

executed by the MC68000, causes an exception. The Macintosh recognizes 
this exception as a call to one of its Operating System or Toolbox 
routines and uses it to determine which routine was reqested. Also 
called a system trap, or simply a trap. 

block: An area of contiguous memory within a heap zone. 

breakpoint: An instruction in an application that causes the immediate 

halting of the application. Using a debugger, you can place a 
breakpoint in an application; when the program halts, you can use the 
debugger to examine the state of the program. 

bundle : A resource that maps local IDs of resources to their actual 
resource IDs; used to provide mappings for file references and icon 
lists needed by the Finder. 

cell: In MacDB, an address or value that can be selected, and 

sometimes changed. 
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conditional assembly: The act of assembling a program that has 
conditions placed in it that determine whether or not specified blocks 
of source should generate code. In the Assembler the IF, ELSE, and 
ENDIF directives are used to perform conditional assembly. 

data fork: The part of a file that contains data accessed via the File 
Manager • 

debugger: An application that aids analysis of ailing applications. 
Debuggers generally provide a way to stop an application, to examine 
the computer’s memory and registers, and to control the operation of 
the application. 

directive: An instruction within a file that is interpreted as a 

command to the Assembler or the Linker. 

document: Whatever you create with Macintosh applications — information 
you enter, modify, view, or save. 

Editor: An application that lets you enter, modify, view, or save 

text, or some other form of information. The Editor is a disk-based 
text editor that lets you create documents larger than will fit into 
memory . 

exception: An error or abnormal condition detected by the processor in 
the course of program execution. System traps are exceptions. Refer 
to the 68000 Reference Manual for more details. 

Executive: The Executive is an application that lets you control the 

use of other applications. If you repeatedly assemble, link, and add 
resources to the same files, you can use the Executive to automate the 
process • 

expression: A collection of symbols (numbers, labels, mathematical 
operators...) that is arranged according to a set of rules (syntax). 
The symbols are evaluated according to that set of rules to produce a 
result . 

extension: In the development system, a period followed by one or more 

letters that is added to a filename to help identify the type of 
information in the file. 

frozen: A state in which the contents of a MacDB window cannot change. 
By default, MacDB windows are changeable (thawed). 

global space: An application’s global space is a fixed block of memory 
that is located relative to A5. It contains all the program storage 
declared using the DS directive. Because it never moves, it is ideal 
storage for data shared between segments. 

heap: An area of memory in which space is dynamically allocated and 
released on demand, using the Memory Manager. 
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jump table: A table that contains one entry for each routine that is 
used by more than one segment. It is a channel of communication 
between relocatable segments, and even allows segments to be removed 
from memory until called by the active segment. 

linker: In the development system, an application that connects .Rel 

files (produced by the Assembler) together into an application. 

machine language: The language that the microprocessor itself 
understands. The Assembler and Linker together translate an 
assembly-language program that you can understand into a 
machine-language program that the Macintosh can understand. 

macro instruction: Consists of a name and a list of parameters. When 
assembled, the macro call is replaced by the list of instructions it 
represents, and the parameters are placed into that list of 
instructions, as appropriate. Just as subroutines are a way of 
generalizing similar pieces of code, macros are a way of generalizing 
similar pieces of text. 

MacWorks : A program that runs on a Lisa computer and that allows the 
Lisa to run Macintosh software. 

modem port: On a Macintosh, the port that has the modem icon above it. 
Also known as port A. 

Nub: In the context of the development system, a program you should 

run on the Macintosh on which you wish to debug your program. MacDB, 
running on another Macintosh, can then examine your program by 
communicating with the nub over a serial cable. 

operand: A quantity upon which an operation is performed. In the 

expression A + B, the operands are A and B, and + is the operator. In 
the assembly-language instruction MOVE D0,D1, the operands are D0 and 
Dl. 

operator: A character or characters that represent an operation to be 
performed. Operators perform operations upon operands. 

packed symbol file: A file that equates values to symbols. Like a text 
file composed of EQU statements, but in a much more compact form. To 
create a packed symbol file, run PackSyms on a .Sym file. 

parameter: In a macro call, a text-string that is to be placed 

literally into the list of instructions that the macro represents. 

Each parameter replaces all instances of the argument that is a 
placeholder for it. 

Pascal string: A Pascal string starts on a word boundary. It consists 
of a byte containing the length of the string followed by bytes 
containing the ASCII codes of the characters in the string. 

precedence: In an expression, the order in which operations are 

performed. For example, in expressions used in the Assembler, 
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multiplication is performed before addition (with the exception that 
operations in parentheses are performed first). 

printer port: On a Macintosh, the port that has the printer icon above 
it. Also referred to as port B. The machine that runs the MacDB 
debugger must always be connected to the other machine by this port. 

program counter: The register in the 68000 that points to the memory 
address that contains the assembly-language instruction that is 
currently being executed. 

port A: On a Macintosh, the port that has the modem icon above it. 

port B: On a Macintosh, the port that has the printer icon above it. 
The machine that runs the MacDB debugger must always be connected to 
the other machine by this port. 

register: A structure within a microprocessor that holds information, 

that can be rapidly and flexibly changed or moved. The 68000 has data 
registers for general data manipulation, address registers that point 
to memory locations, and other registers crucial to the operation of 
the microprocessor. See also: program counter and stack pointer. 

relocatable: Moveable. The Assembler and Linker produce code segments 
that work regardless of their position in memory. The Segment Loader 
moves segments of code relative to one other by updating the jump table 
that allows communication between segments. Together, these features 
create relocatable applications. 

resource: Data or code stored in a resource file and managed by the 
Resource Manager. Predefined resource formats, such as menus or fonts, 
make possible the easy integration of complex data structures into an 
application. 

Resource Compiler: An application that forms resources from a set of 
definitions, and places them into a resource file. The RMaker 
application is the Resource Compiler; however, the Linker is also able 
to create resources. 

resource fork: The part of a file that contains the resources used by 
an application (such as menus, fonts, and icons) and also the 
application code itself; usually accessed via the Resource Manager. 

RMaker: See Resource Compiler. 

segment: One of several parts into which the code of an application 

may be divided. Not all segments need to be in memory at the same 
time . 

source file: A file that contains information used as input to an 
application. 

stack: An area of memory in which space is allocated and released in 

LIFO (last-in-first-out) order, used primarily for routine parameters, 
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return addresses, local variables, and temporary storage. 

stack pointer (SP): A register that contains the memory address that 
is currently the top of the stack. In the 68000, address register 7 
(A7) is used as the stack pointer. 

symbol table: Data that represents the symbols (variables, constants, 
labels, and routine names) used by a program. The symbol table is 
created by the Assembler and used by the Linker. 

system definition file: A file defining global constants, variables, 
or system traps. The development system is shipped with a set of 
equates files and traps files that contain necessary system 
definitions . 

system heap: A portion of memory reserved for use by the Macintosh 
system software. 

text-only file: A file consisting of a stream of ASCII characters that 
contains no special formatting information. 

thawed: Describes a MacDB window that can be changed. A MacDB window 

that cannot be changed is said to be frozen. 

trace: To examine, one instruction at a time, the execution of a 

program. The MacDB Trace command executes the machine-language 
instruction indicated by the program counter, then it updates its 
windows . 

trap: See A-trap. 
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• (dot) 80 
@ 69 

! command 50 
< command 50 
[ command 50 
] command 50 
( command 50 
) command 50 

* command 69 
$ command 50 

A 

address 31 

aligning 42 
addressing modes 31 
alert 

item 97 
template 96 
•ALIGN directive 43 
align box 65, 71 
aligning 

addresses 42 
columns 21 
anchor box 65 
Anchor command 65, 70 
appending to resource file 94 
application bundle 96 
arguments, macro 38 
•Asm 19, 25 
file list 25 
files 28 
Assembler 8, 25 
directives 35 
errors 8, 133 

file naming conventions 25 

invoking 26 

macros 8 

output files 29 

source files 26, 28 

syntax 29 

assembly-language source programs 
asterisk (*) 30, 69 
A-Trap command (s) 72-73, 86 
attribute byte 44 
Auto Indent command 21 
auto-pop bit 73 

B 

•B extension 32 
binary notation 33 
Bkpts menu 69 
block header 73 


branch instructions 32 
breakpoint 69 
Breakpoints window 64 

C 

cells 66 

Change command 2 1 
changing text 21 
Char command 71 
Clear All command 69 
Clear command 69 
close box 65 
code optimization 32 
columns, aligning 21 
Command-S 29 
comments 

Assembler 30 
RMaker 93 

Compile command 100 
Control 

commands 83 
template 96 
copying text 21 
creator bytes 51, 93-94 
current program location 30 
cutting text 21 

D 

•D file 25, 45 
/Data command 51, 53 
data fork 49, 52 
data registers 31 
data storage 52 
DC directive 41 
DCB directive 42 
debug machine 61 
Debug menu 67 

Debugger See MacDB; MacsBug 
decimal notation 33 
default 

25 font 20 

volume 28 

defined resource types 95 
dialog resource 97 
directives 

Assembler 35 
Linker 43 

printing control 27, 35 
Disassembler commands 88 
disk-based editor 20 
disk drive, stopping 67, 89 
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document 

opening 20 
printing 22 
DS directive 42 
•DUMP directive 40, 44 
Duplicate command 69 

E 

editing 21 
Editor 7, 19 

document names 7 
documents 7, 20 
file naming conventions 19 
invoking 19 
.EJECT directive 35 
ELSE directive 37 
END directive 40 
END IF directive 37 
•ENDM directive 39 
EQU directive 40 
equates 16 
.Err file 26, 29 
errors 

Assembler 8, 133 
Executive 58 
Linker 9, 135 
RMaker 137 
Examine window 64 
exceptions 62, 63, 78, 79 
Execute command 58 
Executive 10, 57 
control file 57 
default name 58 
errors 58 

file naming conventions 57 
invoking 57 
syntax 57-58 
using 58 
expressions 33 
MacsBug 81 

F 

file 

name 28 

naming conventions 6 
opening from Editor 20 
selecting from Assembler 27 
setting creator 51, 93-94 
setting type 51, 93-94 
file reference 98 
file system equates 16 
.Files 19, 25 
.Files files 28 


Filter by Time command 27 
Find command 21 
finding text 21 
512K Mac command 67 
font 

default 20 
monospaced 20 
proportional 21 
Format menu 71 
Frozen command 70 

G 

global equates 16 
global storage 41, 49, 52 
/Globals command 51, 52 
Go Till command 68 
Go To command 68 

H 

Heap Check Off command 67 
Heap Check On command 67 
heap zone 71 
commands 86 

Hex Address command 70 
hexadecimal notation 33 

I 

IF directive 37 
INCLUDE directive 36, 94 
indenting text 21 
initial volume 28 
Inside Macintosh 3 
Inst command 71 
instruction 30 

lines. Assembler 29 
syntax. Assembler 30 
interrupt button 79 
invoking 

Assembler 26 
Editor 19 
Executive 57 
Linker 50 
MacDB 61 
MacsBug 77, 79 
RMaker 100 

J 

.Job 19, 57 
•Job files 10, 58 
jump instructions 32 
jumb table 49 

K 
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L 

• L extension 32 
labels 30, 42 
.LErr 49 
•Link 19, 49 
linked list 72 
Linker 9, 49 
commands 50 
control directives 43 
control file 50, 52 
errors 9, 135 

file naming conventions 49 
invoking 50 

sample control file 53 
Lisa Workshop 90, 93 
LisaBug 78 

list of .Asm files 25 
List command 72 

List to Display command 27, 29 
List to File command 27, 29 
listing, Assembler 27 
•ListToDisp directive 35 
•ListToFile directive 35 
local label 30 
Long command 71 
lowercase letters 29 
•Lst file 26, 29 

M 

M68000 16/32-Bit Microprocessor 
Programmer's Ref erence Manual 3 
MacDB 12-13, 61 
menus 67 
windows 63 

Macintosh , the owner's guide 3 
Macintosh 68000 Development System 
disks 4 
MacNub 62 

.MACRO directive 39 
MACRO 38 
macros 38 

Lisa-style 39 
for numerics 16 
for packages 16 
MacsBug 12, 14, 77-78 
commands 81 
invoking 79 
setting up 77 
syntax 80 
versions 77 
MacWorks 61, 78 
.Map file 9, 49, 73, 74 
master pointer 73, 86 
MaxBug 78 


MDS 1 disk 4 
MDS2 disk 5 
MemBlock command 73 
Memory commands 81 
memory storage 42 
menu(s) 98 

defining 54 
MacDB 67 

miscellaneous MacsBug commands 88 
modes, addressing 31 
monospaced font 20 
Move Left command 21 
Move Right command 21 
MOVEM command 31 

N 

naming 

Assembler files 25 
Editor files 19 
Executive files 57 
files 6 

Linker files 49 
resource files 93 
New command 69 
new document 20 
No Anchor command 65, 70 
No Listing command 27 
•NoList directive 35 
non-string expression 37 
no-op 67, 90 
Normal Output command 27 
/NoUndef command 51 
•NoVerbose directive 35 
/NoVerbose command 51 
Nub 12, 61-62, 63 
numbers 33 
MacsBug 80 

O 

octal notation 33 
128K Mac command 67 
Open command 20 
Open Job File command 58 
opening 

document 20 
files 20 
operations 34 
operators, MacsBug 81 
/Output command 51, 52 
output file 52 

P 

package equates 16 
package macros 16 
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packed symbol files 44, 45 
PackSyms 44 

Pascal String command 71 
PC window 63 
precedence 34 
Print command 22 
printer equates 16 
printing 

control directives 27, 35 
dialog box 22 
document 22 
procedure 98 
Proceed command 63, 68 
program, sample 103 
proportional font 21 
Purge command 74 

Q 

QuickDraw equates 16 
QuickDraw traps 16 

R 

.R file 19, 25, 93, 100 
.R Filter command 100 
REG directive 41 
Register commands 82 
Registers window 63 
•Rel file 8, 9, 29, 41, 53, 93 
removing text 21 
replacing text 21 
Resource Compiler See RMaker 
RESOURCE directive 44, 53 
resource files 93 
adding to 94 
naming 93 
types 95 

resource fork 49, 52 
resources 49, 95 
defining 53 
types of 99 

/Resources command 51, 52, 53 
Resume command 58 
Resume and Re-do Last command 58 
RMaker 15, 93 

creating types 99 
errors 137 
input file 93 
syntax 95-96 
using 100 
replacing 21 
•Rsrc files 93 
Run menu 68 


S 

sample 

Linker control file 53 
program 103 
session 11 

Sample Programs folder 11 

scope 30 

scroll 

arrows 66 
bars 20, 66 
box 66 

Search command 72 
searching for source files 28 
Select File command 27 
selecting 

listing options 27 
source files 27 
SET directive 41 
Set command 69 
Set Startup command 62 
Set Tabs command 21 
setting 

file's creator 51, 93-94 
file’s type 51, 93-94 
setting up 
MacsBug 77 
Debugger 61 

signature bytes 51, 93-94 
size box 66 
size extension 32 
source files 

Assembler 26, 28 
Editor 7, 20 
Executive 57 
Linker 50, 52 
RMaker 93 
start box 65 
stopping 

assembly 29 
disk drive 89 
listing 29 
STRING_FORMAT 36 
strings 33, 36-37, 98 
•Sym file 26, 40, 44, 74 
symbol table 9 
Symbolic Address command 70 
symbols 34, 74 
MacsBug 80 
Symbols menu 73 
syntax 

Assembler 29 
Executive 57-58 
MacsBug 80 
RMaker 95-96 
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system definition files 16 
system error numbers 16 
system traps 72, 84 

T 

tab stops 21 
target machine 61 
template 96 
TermBugA 78 
TermBugB 78 

text literals, MacsBug 80 
text-only files 7, 22, 26 
Thawed command 70 
title bar 65 
Title command 70 
Toolbox equates 16 
Toolbox traps 16 
TP 80 

Trace command 68 
Trace Into ROM command 68 
•TRAP directive 41 
traps 16, 72-73, 84 
type bytes 51, 93-94 
/Type command 51 
typing text 20 


V 

Value command 74 
•Verbose directive 35 
/Verbose command 50 
Verbose Output command 27 
volume 

default 28 
names 6, 28 

W 

• W extension 32 
Wait command 67 
Window menu 69 
window(s) 

Breakpoints 64 
Examine 64 
MacDB 63 
PC 63 

Registers 64 
template 99 
word alignment 42 
Word command 71 
WorksNub 61 

X 

XDEF directive 43 
XREF directive 43 


Y 


U 

/UndefOK command 51 
uppercase letters 29 
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Copyright 

This manual and the software described in it are copyrighted 
with all rights reserved. Under the copyright laws, this manual 
or the software may not be copied, in whole or part, without 
written consent of Apple, except in the normal use of the 
software or to make a backup copy. The same proprietary and 
copyright notices must be affixed to any permitted copies as 
were affixed to the original. This exception does not allow 
copies to be made for others, whether or not sold, but all of the 
material purchased (with all backup copies) may be sold, 
given, or loaned to another person. Under the law, copying 
includes translating into another language or format. 

You may use the software on any computer owned by you, but 
extra copies cannot be made for this purpose. For some 
products, a multiuse license may be purchased to allow the 
software to be used on more than one computer owned by the 
purchaser, including a shared-disk system. (Contact your 
authorized Apple dealer for information on multiuse licenses.) 

©1984 Apple Computer, Inc. 

20525 Mariani Ave. 

Cupertino, CA 95014 
(408)996-1010 

Apple, the Apple logo, and Lisa are trademarks of Apple 
Computer, Inc. 

Macintosh is a trademark of McIntosh Laboratory, Inc. and is 
being used with express permission of its owner. 

Simultaneously published in the U.S.A. and Canada. 


Limited Warranty on Media and Manuals 

If you discover physical defects in the media on which this 
software is distributed, or in the manuals distributed with the 
software, Apple will replace the media or manuals at no charge 
to you, provided you return the item to be replaced with proof 
of purchase to Apple or an authorized Apple dealer during the 
90-day period after you purchased the software. In some 
countries the replacement period may be different; check with 
your authorized Apple dealer. 


ALL IMPLIED WARRANTIES ON THE MEDIA AND 
MANUAL, INCLUDING IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
PURPOSE, ARE LIMITED IN DURATION TO NINETY (90) 
DAYS FROM THE DATE OF THE ORIGINAL RETAIL 
PURCHASE OF THIS PRODUCT. 




Even though Apple has tested the software and reviewed the 
documentation, APPLE MAKES NO WARRANTY OR 
REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH 
RESPECT TO THIS SOFTWARE, ITS QUALITY, 
PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A 
PARTICULAR PURPOSE. AS A RESULT, THIS SOFTWARE 
IS SOLD “AS IS,” AND YOU, THE PURCHASER, ARE 
ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND 
PERFORMANCE. 

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, 
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL 
DAMAGES RESULTING FROM ANY DEFECT IN THE 
SOFTWARE OR ITS DOCUMENTATION, even if advised of 
the possibility of such damages. In particular, Apple shall have 
no liability for any programs or data stored in or used with 
Apple products, including the costs of recovering such 
programs or data. 

THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE 
EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR 
WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, 
or employee is authorized to make any modification, 
extension, or addition to this warranty. 


Some states do not allow the exclusion or limitation of implied 
warranties or liability for incidental or consequential damages, 
so the above limitation or exclusion may not apply to you. This 
warranty gives you specific legal rights, and you may also have 
other rights which vary from state to state. 
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File Naming Conventions 

Name Created by Contents 


Name • Asm 

Edit 

Assembler source file 

Name .Files 

Edit 

List of separate assemblies to be performed 

Name. Re 1 

Asm 

Relocatable module with symbol table information 

Name.Lst 

Asm 

Assembler listing 

Name .Err 

Asm 

Assembly errors 

Name • Sym 

Asm 

Symbol table file, generated by .DUMP directive 

Name • D 

PackSyms 

Symbol table, used as input to Asm; packed version 
generated by running PackSyms on .Sym files 

Name . Link 

Edit 

Files to link; Linker listing on/off; where to 
begin segments, resources, data 

Name 

Link 

Application 

Name .LErr 

Link 

Errors that occurred during linking 

Name .Map 

Link 

Symbol table for MacDB and Linker listing 

Name • Job 

Edit 

Executive control program; specifies names of 
applications to be run and files to be passed as 
input to applications 

Name . R 

Edit 

RMaker input file; contains resource definitions 

Name.Rsrc 

RMaker 

RMaker output file 
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L, 

OOOI 
1 0 1 1 0 
OIOII 


Both.Rsrc 



Both 




Both. Map 


Resource 
file for the 
application 


Executable 
object file 
(an Application!) 



MacsBug 

Non-symbolic, 

one-Macintosh 

debugger 




Symbol table 
and listing 
(if requested) 
Used by MacDB 


MacDB 


Symbolic 

two-Macintosh 

debugger 


List of 
errors 
from linking 

Both.LErr 



Both .Job 





















This book’s binding lets it lie 
flat while you’re working 
with your Macintosh. When 
you’re using the book, keep 
the wraparound endflap 
tucked inside the back cover. 
To make it easy to spot the title 
when the book’s on a shelf, 
fold the flap inside the front 
cover and set the book on the 
shelf with the title visible. 
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